[MISC] Sort subsections within sections alphabetically #1366
Conversation
yarikoptic
force-pushed
the
enh-sort-sections
branch
from
b92f997 to
d446ab2
Compare
I rebased and added a comment for each of those sections. AFAIK comments are ok for yaml so hopefully it would not break any workflow. Check it out |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #1366 +/- ##
=======================================
Coverage 88.65% 88.65%
=======================================
Files 11 11
Lines 1084 1084
=======================================
Hits 961 961
Misses 123 123 ☔ View full report in Codecov by Sentry. |
mkdocs.yml
Outdated
| - Intracranial Electroencephalography: modality-specific-files/intracranial-electroencephalography.md | ||
| - Task events: modality-specific-files/task-events.md | ||
| - Physiological and other continuous recordings: modality-specific-files/physiological-and-other-continuous-recordings.md | ||
| - Modality specific files: # keep sections in sorted order when adding/editing | ||
| - Behavioral experiments (with no neural recordings): modality-specific-files/behavioral-experiments.md |
There was a problem hiding this comment.
Why do we want these sorted alphabetically? I agree that order of addition to the spec is not ideal, but this feels unintuitive. I would expect EEG/MEG/iEEG/NIRS to be near each other, for example.
There was a problem hiding this comment.
In case of ambiguity I prefer "explicitness" of sorted order. It has been already many times I had to search up for a section because I managed to miss it in some "intuitive" order.
If there is no "flow" through the sections requiring some to precede another (is there?) I would really prefer explicit alphabetic sorting even if it would not have some "intuitive feel" ;)
There was a problem hiding this comment.
My intuitive feel was different and actually close to the proposal of @yarikoptic ... The first time I rendered the doc for the BEP020 I though my modifications didn't work as i couldn't find it in the top of the list ("Eyetracking" starting with "E")... this is why i changed it first, before being noticed that it couldn't be part of my PR.
mkdocs.yml
Outdated
| - Physiological and other continuous recordings: modality-specific-files/physiological-and-other-continuous-recordings.md | ||
| - Positron Emission Tomography: modality-specific-files/positron-emission-tomography.md | ||
| - Task events: modality-specific-files/task-events.md | ||
| - Derivatives: # keep sections in sorted order when adding/editing |
There was a problem hiding this comment.
I guess it's lucky that derivatives were already sorted. But these are also sorted from "most broadly applicable" to "most specific".
There was a problem hiding this comment.
yeah -- here may be we could leave as is without comment
mkdocs.yml
Outdated
| - BIDS Derivatives: derivatives/introduction.md | ||
| - Common data types and metadata: derivatives/common-data-types.md | ||
| - Imaging data types: derivatives/imaging.md | ||
| - Longitudinal and multi-site studies: longitudinal-and-multi-site-studies.md | ||
| - Glossary: glossary.md | ||
| - BIDS Extension Proposals: extensions.md | ||
| - Appendix: | ||
| - Appendix: # keep sections in sorted order when adding/editing | ||
| - Arterial Spin Labeling: appendices/arterial-spin-labeling.md | ||
| - Contributors: appendices/contributors.md |
There was a problem hiding this comment.
Similarly, I think Contributors, Licenses, Entities, Units, etc were at the front for being more broadly useful.
There was a problem hiding this comment.
well, meanwhile it became
Schema
Contributors
Licenses
Entity table
Entities
File collections
Units
so Units are far from the front etc attesting to the point that without clear deterministic order opinions would differ and overall leading to some arbitrary order favoring some and disfavoring others
| - The BIDS Starter Kit: | ||
| - Website: https://bids-standard.github.io/bids-starter-kit | ||
| - Tutorials: https://bids-standard.github.io/bids-starter-kit/tutorials/tutorials.html | ||
| - The BIDS Starter Kit: # keep sections in sorted order when adding/editing | ||
| - GitHub repository: https://github.com/bids-standard/bids-starter-kit |
There was a problem hiding this comment.
Why should the GitHub source repo be prioritized over rendered docs?
There was a problem hiding this comment.
Just the same logic -- explicit ordering, and who knows what I am looking for ? (I often come to RTD to find the original repo behind it). Having said that -- we could though make it into Sources (GitHub): instead and bring down the line/make robust to change in hosting provider.
There was a problem hiding this comment.
+1 for Sources (GitHub)
I often come to RTD to find the original repo behind it
I also do that, but I don't think that's necessarily a representative behavior for BIDS users ... I am still fine with the proposed change of ordering alphabetically as I think it has more advantages than drawbacks.
sappelhoff
changed the title
There was a problem hiding this comment.
I think I am fine with alphabetical ordering. Once you know what you are looking for, it'll be easier to find.
The drawback of course is, that new visitors to the spec don't get the subsections in "our subjective order of relevance" (e.g., the "Units" appendix before the ASL appendix).
Remi-Gau
added
opinions wanted
I was feeling the need for it each time I was navigating BIDS, but seeing https://github.com/bids-standard/bids-specification/pull/1128/files#diff-98d0f806abc9af24e6a7c545d3d77e8f9ad57643e27211d7a7b896113e420ed2 suggesting the same made me propose it. I think having subsections sorted where there is no really really a requirement for order helps visitor to navigate the document/website instead of doing linear search among all subsections.
yarikoptic
force-pushed
the
enh-sort-sections
branch
from
d446ab2 to
d6fcba6
Compare
|
Dear participants and other @bids-maintenance folks! I have resolved conflicts and commented a little more. I would appreciate your final comments/decisions/actions: IMHO, especially accounting for changes which happened to the menu items meanwhile, a deterministic order (e.g. sorted) would be beneficial and would reduce cognitive burden in adding new ones and navigating the website where the list of menu items is only growing and current, mostly "evolutional", order does not really make sense. |
I was feeling the need for it each time I was navigating BIDS, but seeing
https://github.com/bids-standard/bids-specification/pull/1128/files#diff-98d0f806abc9af24e6a7c545d3d77e8f9ad57643e27211d7a7b896113e420ed2 suggesting the same made me propose it.
I think having subsections sorted where there is no really really a requirement for order helps visitor to navigate the document/website instead of doing linear search among all subsections.