-
Notifications
You must be signed in to change notification settings - Fork 137
Description
Description
There is currently no shared reference for how documentation should be written. This leads to inconsistencies in how different sections (User Guide, How-to, Tutorials, User Reference, etc. ) present examples, explain arguments, and cross-link content. This also makes it harder for contributors who would like to help by working on the docs (as opposed to the code) for earthaccess. This Style Guide would likely live in the "Work with us" section of the docs near all the pages on contributing.
I propose the following:
- Draft a style guide with rules for formatting and structure (e.g., when to use code snippets vs. full examples, User Guise.. if it stays that name... vs. Tutorials/ How-To, etc.). A "What goes where" for all our docs, basically.
- Since the site uses readthedocs, we should include some specific instructions/ content on working with it... probably can find some good content to link out to here: https://about.readthedocs.com
- Best practices that contributors want maintained across the docs (things like the YAML feedback in issue 878 below)
- The Style Guide can be applied to existing docs as sections are revised
Related issues:
#449 : all about the contributing.md file, where we may want to include a section specifically about docs contributions.
#878 : a specific request to be added to the new style guide.
#1194 : issue about the muddiness across content types (which could be cleared up with a style guide).
Metadata
Metadata
Assignees
Labels
Type
Projects
Status