Even a good product won't be used if the guides and tutorials are esoteric, so what is the correct way to create a document?
No matter how good a product is, it is difficult to expand the number of users if the documentation of the product is difficult.
The documentation system — Documentation system documentation
https://documentation.divio.com/
Many people realize that a good product will not increase the number of users without good documents, but there are many cases where document creation fails because they do not know the 'correct document creation method'. Divio points out. Divio applies the document to the two axes of 'practical or theoretical', 'useful during learning or work', and classifies it into four categories: 'tutorial', 'How To guide', 'reference', and 'explanation / discussion'. doing.
◆ Tutorial
The tutorial is 'you can experience a series of steps to use a certain product'. Divio pointed out that acquiring new users wouldn't work because without tutorials there would be no way to understand the product. The important thing in the tutorial is that the reader is happy and confident. It is necessary to have a mechanism that allows the reader to feel confident smoothly, such as 'actually moving the hand', 'immediately giving results', and 'checking the operation in various environments'.
On the contrary, if it leads to the confidence of the reader, it does not matter that 'the procedure is different from the usual one' or 'it does not cover everything that can be done'. Rather, Divio says it's good to have easy-to-understand steps for first-time users and to limit the features included in the steps.
◆ How To Guide
The HowTo guide is 'to solve the problem that actually occurred'. If you compare it to cooking, it is a 'recipe'. Unlike the tutorial, the writer can assume some knowledge and understanding of the reader. Since 'purpose' is the most important factor in the HowTo guide, it is necessary to devise such things as 'showing the path to problem solving in order', 'focusing on a specific problem', and 'giving a clear title'. thing.
The HowTo guide explains that as long as the reader can achieve the purpose, it should be practical, such as avoiding explaining things in detail and giving flexibility so that it can be applied to different environments. I will.
◆ Reference
References are 'technical descriptions of products' such as function and API specifications. The reference is just a description of the function, and in terms of cooking, it is an 'encyclopedia page that describes the varieties and characteristics of food.' The reference needs to be formal and key points, and it is necessary to be aware of the points such as 'align the sentence structure and style', 'do not include explanations and inferences', and 'describe accurately'.
Divio also explains that by aligning the sentence structure with the code base, maintenance costs due to code changes can be reduced.
◆ Explanation and discussion
Explanations and discussions 'clarify a particular topic.' In the cooking analogy, it is a 'book on the history of cooking.' Although explanations and discussions are often omitted compared to other classifications, they help us to understand the product from various perspectives, including its background. In this classification, other classifications such as 'explain why the product is so based on technical constraints and history', 'show alternatives to the current mechanism', and 'consider and discuss dissenting opinions'. Should cover the parts that are not covered by.
In addition, the way of thinking about documents advocated by Divio is incorporated in the documents of the web application framework Django .
Django documentation | Django documentation | Django
https://docs.djangoproject.com/en/3.0/#how-the-documentation-is-organized
Related Posts:
in Note, Posted by darkhorse_log