[FIX] divide readme into 3 parts#374
Conversation
|
Thanks for the tag, @franklin-feingold ! Just for a little more context in reviewing: was there something that prompted this reorganization ? Is there an open issue with more detail ? |
|
The context for this was an out-of-band discussion (which also led to Neurostars #5476) in which we were trying to figure out how people might get lost when coming to the various potential front-pages for BIDS, which include:
I proposed (and nobody strenuously objected), that if someone gets to the repo, they probably want to know one of three things: 1) Where to find the spec; 2) How to learn about BIDS more generally; 3) How to contribute their ideas to BIDS. And we could probably make it a little easier to find resources for each. |
effigies
left a comment
There was a problem hiding this comment.
This LGTM, and is definitely an improvement. I would suggest that we might want to switch from "Using" language. Some concrete suggestions:
emdupre
left a comment
There was a problem hiding this comment.
A few suggestions on phrasing and content, but overall I think delineating use cases is a great idea ! Thanks !!
Co-Authored-By: Chris Markiewicz <effigies@gmail.com> Co-Authored-By: Elizabeth DuPre <emd222@cornell.edu>
emdupre
left a comment
There was a problem hiding this comment.
A suggested small typo fix 😸
Bigger general point: If the division you have in mind is "what you need to get started" vs "where to get help" why don't we do something like:
- Rename "Formatting your data with BIDS" to "When to use BIDS" (sorry, I know I just asked you to change that !)
- Rename "Getting Started" to "Formatting your data with BIDS"
- Move the second heading above "As a dataset curator" i.e. around L22
I don't think this division quite maps on to what @effigies suggested above, but I personally find it a little clearer than what we have right now. WDYT ?
|
Thank you @sappelhoff for the edits! I think this will help with navigating/understanding this repo! Reading through I agree with @emdupre 1st and 3rd points. |
Co-Authored-By: Elizabeth DuPre <emd222@cornell.edu>
|
I disregarded @franklin-feingold's proposal for the second heading for now to give him a chance to re-read this in the new format as suggested by @emdupre. I think it's coming along well now. Thanks for the feedback all of you :) |
| The specification is provided in the form of a webpage, built using | ||
| [MkDocs](https://www.mkdocs.org/) and [Read the Docs](https://readthedocs.org/). | ||
|
|
||
| *Want to learn more about working with BIDS? Have a question, comment, or suggestion?* |
There was a problem hiding this comment.
Light suggestion here would be to convert this into a sub-heading, or add one directly above it. Something like:
## Where to go to learn more
emdupre
left a comment
There was a problem hiding this comment.
One light suggestion, but this LGTM ! Would love to know what everyone else thinks.
Thanks, @sappelhoff ✨
|
Thanks for your help @emdupre |
* upstream/master: (439 commits) [DOC] Auto-generate changelog entry for PR bids-standard#394 Update 01-contributors.md [DOC] Auto-generate changelog entry for PR bids-standard#389 [DOC] Auto-generate changelog entry for PR bids-standard#386 moved list of extension proposals to the main BIDS website section 06-extensions remains, but now points to the main website Typo fix for typo fix Typo fix for typo fix [DOC] Auto-generate changelog entry for PR bids-standard#374 [FIX] Fix some typos and prose style issues [DOC] Auto-generate changelog entry for PR bids-standard#383 restructure according to @emdupre's proposal neurostars for everything not just technical Apply suggestions from code review MNT: Update Pipfile ENH: Append CSS instead of overriding it ENH: Add watermark to drafts [DOC] Auto-generate changelog entry for PR bids-standard#381 Update src/06-extensions.md Retiring moderator duties for BEP021 [DOC] Auto-generate changelog entry for PR bids-standard#380 ...
* upstream/master: (439 commits) [DOC] Auto-generate changelog entry for PR bids-standard#394 Update 01-contributors.md [DOC] Auto-generate changelog entry for PR bids-standard#389 [DOC] Auto-generate changelog entry for PR bids-standard#386 moved list of extension proposals to the main BIDS website section 06-extensions remains, but now points to the main website Typo fix for typo fix Typo fix for typo fix [DOC] Auto-generate changelog entry for PR bids-standard#374 [FIX] Fix some typos and prose style issues [DOC] Auto-generate changelog entry for PR bids-standard#383 restructure according to @emdupre's proposal neurostars for everything not just technical Apply suggestions from code review MNT: Update Pipfile ENH: Append CSS instead of overriding it ENH: Add watermark to drafts [DOC] Auto-generate changelog entry for PR bids-standard#381 Update src/06-extensions.md Retiring moderator duties for BEP021 [DOC] Auto-generate changelog entry for PR bids-standard#380 ...
This is an attempt to make the README of the specification repository a bit cleaner.
What do you think? What else should be addressed?