Documentation

  • If your product/tool/process documentation is not good enough, people will not use it.
  • The documentation for a project should live in the same repository as the code itself.
    • Update documentation in lockstep when updating the codebase.
    • Documentation should be versioned.
    • Documentation changes should be reviewed in the same way as your code.
  • Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, technical reference and explanation. Each of them requires a distinct mode of writing.
    • A tutorial is learning-oriented, allows the newcomer to get started, similar to a lesson. E.g: teaching a small child how to cook.
    • A how-to guide is goal-oriented, shows how to solve a specific problem with a series of steps. E.g: a recipe in a cookery book.
    • An explanation is understanding-oriented, provides background and context. E.g: an article on culinary social history.
    • A reference guide is information-oriented, describes the machinery and is accurate and complete. E.g: a reference encyclopedia article.
  • If someone’s having to read your docs, it’s not “simple”. Remove filler words.
  • Principles to keep in mind when writing documentation.
    • The purpose of technical writing is to help users accomplish tasks as quickly and effectively as possible.
    • People learn by doing, prefer to be shown and not told.
    • Get users to their first success quickly.
    • There is more than one type of documentation.
    • Use second person: “you” rather than “we”.
    • Keep it simple, write in plain language.
    • Use active voice: make clear who’s performing the action.
  • As you are working in a team, then you have to address the problem of shared understanding. This is where documentation come in.
  • Use the imperative mood in descriptions and instructions. Use concise action-oriented sentences, written from the user’s perspective.
    • When writing instructions, anywhere you say “You should X” or “You can X,” replace it with the imperative mood of the verb.
  • Ask the below two questions before writing:
    1. Who am I writing this for?
    2. What are the top 1-3 takeaways after someone’s read?
  • Model your reader’s current understanding and guide them to your perspective. Anticipate and preemptively address potential reader objections. The goal is to convince readers (especially yourself) that your approach is optimal through clear logical progression.
  • Write simply:
    • Use fewer than 30 words per sentence.
    • Use ordinary words and simple sentences.
    • Remove fluff.
    • Remove weasel words. Replace adjectives with data or details.
    • Ask the “So what” question to every sentence that you write.
    • Prefer active voice to passive.
  • Most docs are short-lived and used for point-in-time discussions. However, some documents serve for a longer time. To have your writing stand the test of time, avoid using references that change with time or location.
  • Documentation valuable if it captures the design decision and intention at the time of the creation of the software, rather than the functionality of the software itself.

Resources

READMEs