# 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](https://diataxis.fr/) needs to include and be structured around its four different functions: [tutorials, how-to guides, technical reference and explanation](https://documentation.divio.com/introduction/). 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"](https://justsimply.dev/). Remove filler words. - [Principles to keep in mind when writing documentation](https://mkaz.blog/misc/notes-on-technical-writing/). - 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](https://developers.google.com/style/person): "you" rather than "we". - Keep it simple, write in plain language. - [Use active voice](https://developers.google.com/style/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](https://surfingcomplexity.blog/2022/11/24/writing-docs-well-why-should-a-software-engineer-care/). This is where documentation come in. - [Use the imperative mood in descriptions and instructions](https://twitter.com/kepano/status/1751354613041872985). 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](https://zodvik.com/posts/on-writing-well/): - 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](https://docs.microsoft.com/en-us/style-guide/welcome/) - [Google Documentation Style Guide](https://developers.google.com/style) - [Mailchimp Content Style Guide](https://styleguide.mailchimp.com/voice-and-tone/) - [18F Content Guide](http://web.archive.org/web/20230327160033/https://content-guide.18f.gov/our-style/voice-and-tone/) ## READMEs - [Building a README](https://readme.so/). - [How to Write a Great README](https://www.appsmith.com/blog/write-a-great-readme). - [Template](https://www.makeareadme.com/). - [Readme Driven Development](https://tom.preston-werner.com/2010/08/23/readme-driven-development). - [Starship](https://github.com/starship/starship). - [Alacritty](https://github.com/alacritty/alacritty).