Suggestion: Describe & Potentially Modularize the Repository

[TomDonoghue]

I think this repository / tool would benefit from a little more description and documentation on the organization of the repository, and how it all comes together to make the tool work.

Currently, I find it a little difficult to understand how it all comes together. For example, the install instructions describe following the steps in the runMappingViznotebook, but this notebook is sparsely annotated, and I find it unclear how it relates to the project / website as a whole. As far as I can tell, the whole site is hosted off a singular immense html file, and it's unclear how this interacts with the the files in the rest of the repo.

This seems to be a potential issues, since:

• In terms of maintenance, it seems likely that the current structure may be difficult to maintain
• The README welcomes the the idea of outside contributions, but I think it would currently be difficult for potential contributors to work through the current structure to add or adapt elements.

Collectively, my worry is that if the current repository is difficult to maintain, and difficult for new people to interact with, this may hinder the long term viability of this as an educational tool.

Possible suggestions:

• Add a description of the repository, that indicates what the different folders and elements of the project are. Ideally, this includes specific descriptions of the layout, and a brief top level overview of how the tool works to create the website.
• Flesh out a contributors guide, with guidelines on how one can get started working with or editing the current tool.
• If there is Python code that can be used to rebuild some of the data & and analyses, maybe this can be organized into a set of scripts, with an outline of how to re-run them if needed.
  • I am unclear, for example, if runMappingViz is a required precursor to rebuilding the site, and/or what is in the PCA folder.
• Can index.html be split up and organized into a more modular structure?
  • If for some reason not, some meta-description of it's structure, and how it relates to the files in the repo may be useful.

Note: this issue filed as part of doing a review for JOSE (openjournals/jose-reviews#75)

[PaulScotti]

I appreciate the suggestion and hope that we can improve this repository in the ways you suggest in the future. For the moment it would take considerable time to make these changes, although I did go ahead and revise the runMappingViz file to improve readability in terms of how we did PCA and create the functional png maps extracted from Neurosynth. Our primary goal for now is to disseminate this tool (aka the educortex website) to teachers and children rather than work towards improving the ease with which contributors can help improve the tool.

[TomDonoghue]

I get that bigger refactors could be a fair amount of work - I think they don't need to happen now, but maybe could be kept in mind as a potential development milestone.

I also like that you updated runMappingViz but I still feel it's missing an intro - could you perhaps add a markdown cell at the top with a couple sentences on what it does?

As a quick addition, what I think would help the incomer navigate better, what about just a brief 'repository layout' description in the README? This, I think, would lay out the top level logic in a helpful manner. I'm thinking of something like this:
https://github.com/voytekresearch/BandRatios/blob/master/README.md#repository-layout

[PaulScotti]

Added an intro to runMappingViz and also repository layout to the README (thanks for the reference!). And yes, your above suggestions are definitely something I wish we can do as a potential developmental milestone.