Refactor "Developer Guide" into a single doc + include TOC into navigation #66
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Instead of having a separate TOC on the right , it would just expand already present navigation on the left, IMHO making 1. a better use of screen real estate, 2. no longer requiring user to jump with mouse from left to right to navigate
Even withing development notes structure and details were spread out through multiple sections. Moreover deployment section was entirely about the archive but as independent section. IMHO all archive specific descriptions better reside within archive section. I took the other 20_project_structure and melded it with information within 40_development. There might still be some references to dandi-api which are deprecated and should be adjusted, I did not pay full attention to those and just wanted to establish new structure while reducing duplication and expanding coverage.
|
I definitely prefer having all the TOC links all on the left side. I had moved the schematic figure to docs/20_project_structure.md in my current PR, but this file is deleted as part of this PR. Need to sort that out. |
Closed
satra
reviewed
Aug 2, 2022
There was a problem hiding this comment.
this needs a fair bit of refactoring.
- start with an overview of components (perhaps a version of this figure ) and their roles.
- general developer guidelines
- how to contribute etc.,. or pointers to CONTRIBUTING.md
- the current section starts with helpdesk. do you want developers to use the helpdesk or directly go to project issues?
- for each component/group of components provide developer guidelines of how to install/run etc.,.
|
@satra -- those are not just "a fair bit" but rather substantial further refactoring. |
|
we have an alternative RFing of development guide... i might bring TOC later separately |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Decided to include both commits in one PR since it better demonstrate difference in appearance for the first commit change of including TOC within navigation bar on the left (instead of adding it on the right). E.g. how it would look with current RF of the Guide and
webshots
instead of old one
and here is how it looks now (note that TOC is not available due to
#section on top of the file):But if so not desired (I thought it is nice since avoids wild runs of mouse from the left to right, and gives more width for text), I can just drop that commit from the PR.
2nd commit is more profound: I found that we had pretty much multiple points describing components with very overlapping amount of detail between https://www.dandiarchive.org/handbook/20_project_structure/ , https://www.dandiarchive.org/handbook/40_development/#overview and then subsections therein like https://www.dandiarchive.org/handbook/40_development/#technologies-used . So , because they all are placed under "Developer Guide" I just decided to keep it only in 40_development, make it the "Developer Guide" and there structure via sections, not just itemized list, into components. That gives more space to describe each component and provide subsections like we do for
dandi-archiveunder which I placed now relevant (only) to it other sections (Deployment and Technologies).If overall flow is ok, I would then (in this PR or follow up) would like to add a section on other common principles we would like to harmonize across components e.g. Pull Requests - who merges/closes comments/etc.