Nothing Special   »   [go: up one dir, main page]

Skip to content

Writing documentation

Learn how to write technical documentation.

References

Guidelines

Before starting

  • Set up a spell checker in your IDE, even better a "writing assistant" (popular ones LanguageTool, Grammarly).
  • Determine what your audience needs to learn, fit documentation to your audience.

When writing

  • Write in the second person. Refer to your audience as “you” rather than “we”.
  • Create great opening sentences that establish a paragraph's central point.
  • Prefer active voice to passive voice: The mat was sat on by the cat. -> The cat sat on the mat.
  • Prefer task-based headings.
  • Prefer list to long sentences. Use a numbered list when ordering is important and a bulleted list when ordering is irrelevant.
  • Explain and give information progressively.
  • Usage sections should feel like tutorials that call the user to action - e.g. "create a mapping".
  • In tutorials, reinforce concepts with examples, note problems that readers may encounter.

When completed

  • Read documents out loud (to yourself).
  • Ask for review.
  • When using MkDocs, run the live server and verify that the page renders correctly (e.g. code snippets).