Documentation

Introduction

My quick reference notes on writing documentation.

Words

• Define new or unfamiliar terms.
• Use terms consistently.
  • Don’t have multiple names for the same thing.
• Define an acronym on its first use.
  • Don’t cycle between the full term and the acronym.
  • Don’t define an acronym if it’s only going to be used a few times.
• Disambiguate pronouns.
  • Only use a pronoun after introducing the noun.
  • If the pronoun is more than a few words away from the noun then repeat the noun.
  • If you introduce a second noun between your noun and your pronoun, reuse your noun instead of using a pronoun.

Active Voice

• Active voice: actor + verb + target.
• Passive voice: target + verb + (optional) actor.
• Prefer using active voice.
  • Bad: The c++ source code is compiled by clang.
  • Good: Clang compiles the c++ source code.

Clear Sentences

• Reduce imprecise, weak and generic verbs.
  • Bad: This error happens when …
  • Good: The system generates this error when …
• Omit phrases ‘there is’ and ‘there are’.
  • Bad: There is a variable called ‘last_dwell’ that stores the last dwell which was calculated.
  • Good: The variable ‘last_dwell’ stores the last dwell which was calculated.
• Put conditional clauses before instructions (not after).
  • Bad: Call updateConfluence() if you want to update the component’s confluence page.
  • Good: To update the component’s confluence page, call updateConfluence().
• Use second person narrative (“you” rather than “we”).
  • Bad: If we’re using pub/sub …
  • Good: If you’re using pub/sub …

Short Sentences

• Focus each sentence on a single idea.
• Convert long sentences to lists.
• Eliminate extraneous words.
  • Bad: Calling the registerSelf method causes the triggering of the RegisterTaskTopic.
  • Good: The registerSelf method triggers the RegisterTaskTopic.
• Subordinate clauses should extend the sentence and not branch off into a separate idea.
  • ‘That’ introduces an essential subordinate clause.
  • ‘Which’ introduces a non-essential subordinate clause.

Lists

• Use bulleted lists for unordered items.
• Use numbered lists for ordered items.
• Reduce embedded lists (also known as run-in lists).
• Keep list items parallel (same grammar, logical category, capitalization & punctuation).
• Start numbered lists with imperative verbs.

Tables

• Label each column with a meaningful header.
• Avoid putting too much text into a table cell.
• Strive for parallelism within individual columns (same grammar, logical category, capitalization & punctuation).

Paragraphs

• The opening sentence should establish the paragraph’s central point.
• Focus each paragraph on a single topic.
• Paragraphs should contain around 3 - 7 sentences.

Audience

• Define your audience.
• Determine what your audience needs to learn.
• Good documentation = “knowledge needed to do a task” - “the audience’s current knowledge”.

Longer Documents

• State your document’s scope.
• You can also define its non-scope.
• Write an executive summary (a TL;DR).

Formatting

• Put code-related text in code font.
• Prefer SVG files and PNG files.
• Use descriptive link text.
  • Bad: Want more? Click here!
  • Good: For more information, visit the Volume Search landing page.

Editing

• Think like your audience.
• Read the documentation aloud.
• Come back to it later.
• Ask a peer to review it.
• Run a spell checker on the document.

Illustrations

• Write the caption before creating the illustration to ensure the illustration matches the goal.
• Constrain the amount of information in a single drawing.
• Don’t put more than 1 paragraph’s worth of information in a single diagram.
• Focus the reader’s attention.
  • Use arrows or circles to highlight the important part in screenshots.

Sample Code

• Sample code should set the best way to interact with your API.
• Maintain the sample code.
  • Over time the system may change and so will the sample code.
  • Test the sample code actually works.
• Example the anti-example.
  • In addition to showing readers what to do, it is sometimes beneficial to show readers what not to do.