Documentation#

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 deploy repository.

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.

Required documentation#

The README.md file or documentation website must document how to:

Install requirements
Initialize services (e.g. via database migrations)
Configure settings (e.g. via environment variables)
Perform common actions, like:
- Start server
- Translate text
- Run tests

Writing documentation#

Technical documentation should be clear and unambiguous. It should sacrifice style, flair, brevity and personality in favor of clarity.

General structure#

Determine which type of documentation you are writing
Separate the types of documentation (different pages or, at minimum, different sections), but link between them

How-to guides#

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.

Word choice#

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.

Shell examples#

Documentation and examples for external users should use sh or bash syntax. Documentation for internal users can use fish syntax.