Documentation guidelines

This document serves as a starting point, self-assessment, and review guide for writing documentation. Some of this is borrowed from a discussion between maintainers which occurred after reading “Docs for Developers”.

Front Matter

These are some aspects to consider when starting the document.

Type: (README, “Getting Started”, Conceptual, Procedural [tutorial/how-to/guide], Reference [API reference, Glossary, Troubleshooting, Changelog])
Audience:
Purpose:
Title:
Outline:

Completion Questions

These questions can help you determine when to be done drafting a document.

  • Does the headline summarize the document’s goal?

  • Do headings adequately summarize the document?

  • Does your draft address your reader’s needs from start to finish?

  • Does the flow of information make sense to your reader?

  • Does the draft address any issues you found in your friction log?

  • Does your draft correctly follow any documentation patterns or a template?

  • Have you tested and verified that any and all procedures work?

Reviewing

These are steps to check when reviewing a document.

  • Title is short and specific

  • Headers are logically ordered and consistent

  • Purpose of document is explained in the first paragraph

  • Procedures are tested and work

  • Any technical concepts are explained or linked to

  • Document follows structure from templates

  • All links work

  • Spelling and grammar checker has been run

  • Graphics and images are clear, useful, and have alt text where possible)

  • Any prerequisites and next steps are defined