Types of documentation#
Read The Documentation System to learn about the four types of documentation we write: tutorials, how-to guides, technical reference and explanation.
Locations of documentation#
External documentation can be accessed via the Docs links on this page.
Internal documentation can be accessed via the User Guides in the
Documentation should be maximally proximate to the thing it is documenting. For example, to document what a method in software does, it’s best to author that documentation as a heredoc in the method itself, instead of in a separate document.
README.md file or documentation website must document how to:
Initialize services (e.g. via database migrations)
Configure settings (e.g. via environment variables)
Perform common actions, like:
Technical documentation should be clear and unambiguous. It should sacrifice style, flair, brevity and personality in favor of clarity.
Determine which type of documentation you are writing
Separate the types of documentation (different pages or, at minimum, different sections), but link between them
Give explicit instructions. Don’t make me think.
Don’t include information that is not directly relevant to the how-to guide.
Use numbered lists for instructions. Nest sub-tasks to give structure to long lists.
Give example commands, but don’t include default arguments or any other extraneous detail.
It’s okay to put many how-to guides on one page, but the setup guide should be on its own.
- Use consistent terms and constructions
For example: “connect to the server,” not a mix of “go to the server”, “access the machine”, etc.
- Use specific and non-metaphorical language
For example: “connect” to the server, not “go” to the server.
- Link unfamiliar terms to external documentation, if available
For example: concatenated JSON.
Documentation and examples for external users should use
bash syntax. Documentation for internal users can use