davidgasquez.com
📚 Personal bits of knowledge
1# Documentation
2
3- If your product/tool/process documentation is not good enough, people will not use it.
4- The documentation for a project should live in the same repository as the code itself.
5 - Update documentation in lockstep when updating the codebase.
6 - Documentation should be **versioned**.
7 - Documentation changes should be reviewed in the same way as your code.
8- [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.
9 - A tutorial is learning-oriented, allows the newcomer to get started, similar to a lesson. E.g: teaching a small child how to cook.
10 - 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.
11 - An explanation is understanding-oriented, provides background and context. E.g: an article on culinary social history.
12 - A reference guide is information-oriented, describes the machinery and is accurate and complete. E.g: a reference encyclopedia article.
13- [If someone's having to read your docs, it's not "simple"](https://justsimply.dev/). Remove filler words.
14- [Principles to keep in mind when writing documentation](https://mkaz.blog/misc/notes-on-technical-writing/).
15 - The purpose of technical writing is to help users accomplish tasks as quickly and effectively as possible.
16 - People learn by doing, prefer to be shown and not told.
17 - Get users to their first success quickly.
18 - There is more than one type of documentation.
19 - [Use second person](https://developers.google.com/style/person): "you" rather than "we".
20 - Keep it simple, write in plain language.
21 - [Use active voice](https://developers.google.com/style/voice): make clear who's performing the action.
22- [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.
23- [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.
24 - When writing instructions, anywhere you say "You should X" or "You can X," replace it with the imperative mood of the verb.
25- Ask the below two questions before writing:
26 1. Who am I writing this for?
27 2. What are the top 1-3 takeaways after someone's read?
28- [Model your reader's current understanding and guide them to your perspective](https://grantslatton.com/how-to-design-document). Anticipate and preemptively address potential reader objections. The goal is to convince readers (especially yourself) that your approach is optimal through clear logical progression.
29- [Write simply](https://zodvik.com/posts/on-writing-well/):
30 - Use fewer than 30 words per sentence.
31 - Use ordinary words and simple sentences.
32 - Remove fluff.
33 - Remove weasel words. Replace adjectives with data or details.
34 - Ask the "So what" question to every sentence that you write.
35 - Prefer active voice to passive.
36- 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.
37- Documentation is 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.
38
39## Resources
40
41- [Microsoft Documentation Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/)
42- [Google Documentation Style Guide](https://developers.google.com/style)
43- [Mailchimp Content Style Guide](https://styleguide.mailchimp.com/voice-and-tone/)
44- [18F Content Guide](http://web.archive.org/web/20230327160033/https://content-guide.18f.gov/our-style/voice-and-tone/)
45
46## READMEs
47
48- [Building a README](https://readme.so/).
49- [How to Write a Great README](https://www.appsmith.com/blog/write-a-great-readme).
50 - [Template](https://www.makeareadme.com/).
51- [Readme Driven Development](https://tom.preston-werner.com/2010/08/23/readme-driven-development).
52- [Starship](https://github.com/starship/starship).
53- [Alacritty](https://github.com/alacritty/alacritty).