Navigation structure changes#1360
Conversation
Building off the conversation here: #1200 I made some changes to the navigation to categorize content into more diataxis-esque groupings. Aside from that, we were inconsistent in our capitalization, so I tried to address that as well. Let me know if this is in line with what you two were thinking, @mfisher87 and @asteiker !
saberbrasher
added
the
impact: documentation
|
I will automatically update this comment whenever this PR is modified
|
After discussion, moved "How-to" content above "Explanation" and removed the "s" from "How-tos".
|
After chatting with @andypbarrett and @asteiker, I made a couple of other small changes:
|
| - "Community calendar": "calendar.md" | ||
| - "External resources": "resources.md" | ||
| - "About Us": "about-us.md" | ||
| - "About us": "about-us.md" |
There was a problem hiding this comment.
💯 sentence case!!! This is one of my pet peeves, thanks for fixing it :) We should only use title case for titles of papers or other proper nouns (including class names). And this should probably go in our documentation style guide.
| - "Collection queries": "api/collections/collections-query.md" | ||
| - "Collection results": "api/collections/collections.md" | ||
| - "Collection services": "api/collections/collections-services.md" |
There was a problem hiding this comment.
Not for this PR, just thinking out loud. I'd like to rename some of these pages to remove redundancy, e.g. api/collections/collections-services.md -> api/collections/services.md
| - "Search": "user/search.md" | ||
| - "Access": "user/access.md" | ||
| - "Backwards compatibility": "user/backwards-compatibility.md" | ||
| - Tutorials: |
There was a problem hiding this comment.
Maybe tutorials should go first? I don't feel strongly.
I kind of like Tutorials -> How-to -> Explanation -> Reference because it reflects the general order of an expertise journey. You start with a tutorial, then you learn that you need to understand a specific feature and use a how-to, then you learn you don't understand a design concept and need an explanation, then you feel capable of using only reference materials to guide your work.
Of course, this isn't fully linear, you're going to be linked to explanations from tutorials, and you'll be following a how-to and need more information about an API and navigate over to reference materials. But I think it represents the chronological order in which these different categories are most important.
Again, despite my essay about this, I think it's OK if we keep it where it is.
| - "Code of Conduct": "contributor/code-of-conduct.md" | ||
| - "Topics": | ||
| - "Naming conventions": "contributor/naming-convention.md" | ||
| - "Code of conduct": "contributor/code-of-conduct.md" |
| - "Pull Request (PR) guide": "contributor/pr-guide.md" | ||
| - "Releasing guide": "contributor/releasing.md" | ||
| - "Maintainers guide": "contributor/maintainers-guide.md" | ||
| - "Triaging guide": "contributor/triaging.md" |
There was a problem hiding this comment.
I love the reorganization in the nav, but I also think we should move these files into a directory structure that matches the nav like we have for the user guide. I.e.
contributor/how-to/development.md.
This will break some links, and I think that's OK. We can add redirects if we really care about that, but I don't think that's necessary.
| - "Naming conventions": "contributor/naming-convention.md" | ||
| - "Code of conduct": "contributor/code-of-conduct.md" | ||
| - How-to: | ||
| - "Development guide": "contributor/development.md" |
There was a problem hiding this comment.
| - "Development guide": "contributor/development.md" | |
| - "Develop": "contributor/development.md" |
I'd like to rephrase these to complete the sentence "I want to know how to ___". E.g. "I want to know how to development guide" -> "I want to know how to develop".
"I want to know how to author a PR"
Release a new version
Do common maintenance tasks (this one is a stretch, I imagine someone else will have a better version :))
Triage issues and PRs
etc.
|
pre-commit.ci autofix You may need to |
for more information, see https://pre-commit.ci
|
pre-commit.ci autofix I guess it couldn't fix that in one go? 🤷 |
for more information, see https://pre-commit.ci
|
Unit tests should be resolved by #1367 |
2 participants
Building off the conversation here: #1200 I made some changes to the navigation to categorize content into more diataxis-esque groupings. This would address the third sub-issue Amy identified there. Aside from that, we were inconsistent in our capitalization, so I tried to address that as well. Let me know if this is in line with what you two were thinking, @mfisher87 and @asteiker !
📚 Documentation preview 📚: https://earthaccess--1360.org.readthedocs.build/en/1360/