# Divio Authors - Documentation System (Highlights)  ## Metadata **Cover**:: https://readwise-assets.s3.amazonaws.com/static/images/default-book-icon-5.25188386e520.png **Source**:: #from/readwise **Zettel**:: #zettel/fleeting **Status**:: #x **Authors**:: [[Divio Authors]] **Full Title**:: Documentation System **Category**:: #books #readwise/books **Category Icon**:: 📚 **Highlighted**:: [[2022-08-03]] **Created**:: [[2022-09-26]] ## Highlights ### 1.1 Introduction - documentation needs to include and be structured around its four different functions: tutorials, how-to guides, technical reference and explanation. (Page 8) #pic pic  ### 1.2 Tutorials - Under your instruction, the student will execute a series of actions to achieve some end. (Page 9) A specific objective - What you teach the child to cook isn’t really important. What’s important is that the child finds it enjoyable, and gains confidence, and wants to do it again. (Page 10) #### 1.2.2 How to write good tutorials - Allow the user to learn by doing (Page 10) - Ensure the user sees results immediately (Page 11) - Focus on concrete steps, not abstract concepts (Page 11) - The temptation to introduce abstraction is huge; it is after all how most computing derives its power. But all learning proceeds from the particular and concrete to the general and abstract, and asking the learner to appreciate levels of abstraction before they have even had a chance to grasp the concrete is poor teaching. (Page 11) #star - Don’t explain anything the learner doesn’t need to know in order to complete the tutorial. (Page 12) - Focus only on the steps the user needs to take (Page 12) ### 1.3 How-to guides - How-to guides take the reader through the steps required to solve a real-world problem. (Page 12) - How-to guides are wholly distinct from tutorials and must not be confused with them: • A tutorial is what you decide a beginner needs to know. • A how-to guide is an answer to a question that only a user with some experience could even formulate. (Page 12) - Someone who has never cooked before can’t be expected to follow a recipe with success, so a recipe is not a substitute for a cooking lesson. At the same time, someone who reads a recipe would be irritated to find that it tries to teach basics that they know already, or contains irrelevant discussion of the ingredients. (Page 13) Analogy of how-to guide with cooking #### 1.3.2 How to write good how-to guides - How-to guides must contain a list of steps, that need to be followed in order (just like tutorials do). You don’t have to start at the very beginning, just at a reasonable starting point. (Page 13) - A how-to guide should not explain things. (Page 14) - A how-to guide should allow for slightly different ways of doing the same thing. It needs just enough flexibility in it that the user can see how it will apply to slightly different examples from the one you describe, or understand how to adapt it to a slightly different system or configuration from the one you’re assuming. Don’t be so specific that the guide is useless for anything except the exact purpose you have in mind. (Page 14) - Practical usability is more valuable than completeness. Tutorials need to be complete, end-to-end guides; how-to guides do not. They can start and end where it seems appropriate to you. They don’t need to mention everything that there is to mention either, just because it is related to the topic. (Page 14) ### 1.4 Reference guides - By all means technical reference can contain examples to illustrate usage, but it should not attempt to explain basic concepts, or how to achieve common tasks. (Page 15) #### 1.4.2 How to write good reference guides - Structure the documentation around the code (Page 16) - The only job of technical reference is to describe, as clearly and completely as possible. Anything else (explanation, discussion, instruction, speculation, opinion) is not only a distraction, but will make it harder to use and maintain. (Page 17) ### 1.5 Explanation - Sometimes, the section exists, but has a name such as Background or Other notes or Key topics (Page 18) - It doesn’t teach, it’s not a collection of recipes, and it doesn’t just describe. Instead, it analyses, considers things from multiple perspectives. It might explain why it is we now do things the way we do, or even describe bad ways of doing things, or obscure alternatives. (Page 19) ### 1.5.2 How to write a good explanation - Explanations are the place for background and context (Page 19) - Explanation can consider alternatives, or multiple different approaches to the same question. (Page 19) - Explanation should do things that the other parts of the documentation do not. It’s not the place of an explanation to instruct the user in how to do something. (Page 19) - Good examples of the scheme in substantial projects include: • the Divio Developer Handbook • Django’s documentation • django CMS’s documentation (Page 22)