Documentation organization
Documentation organization
This documentation tries to follow the Diátaxis documentation structure, which is a systematic approach to technical documentation authoring. The only exception it development documentation which we choose not to be part of the Diátaxis structure, but it is a common part of the software documentation.
Documentation isn’t just one thing, it is made up of four different parts which include — Tutorials, How-to guides, Explanations, and References.
| Tutorials | How-to guides | References | Explanations | |
|---|---|---|---|---|
| what they do | introduce, educate, lead | guide | state, describe, inform | explain, clarify, discuss |
| answers the question | “Can you teach me to…?” | “How do I…?” | “What is…?” | “Why…?” |
| oriented to | learning | goals | information | understanding |
| purpose | to provide a learning experience | to help achieve a particular goal | to describe the machinery | to illuminate a topic |
| form | a lesson | a series of steps | dry description | discursive explanation |
| analogy | teaching a child how to cook | a recipe in a cookery book | information on the back of a food packet | an article on culinary social history |
Note
For more information, you can visit the Diátaxis website or read the Diátaxis documentation. Also, there is this good article How to Structure Documentation using the Diataxis Framework from Tech Writers Hub Medium blog.
Last updated on