- 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:
- Who am I writing this for?
- 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.