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?
• 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.

Resources

• Microsoft Documentation Style Guide
• Google Documentation Style Guide
• Mailchimp Content Style Guide
• 18F Content Guide

READMEs

• Building a README.
• How to Write a Great README.
  • Template
• Starship.
• Alacritty.