Mike's Notes
This month's job is to design and build a working help system for users. I'm using the Diátaxis approach.
Resources
- https://idratherbewriting.com/blog/what-is-diataxis-documentation-framework
- https://danielsieger.com/blog/2023/04/24/framework-for-better-documentation.html
- https://diataxis.fr/
- https://diataxis.fr/map/
- https://ubuntu.com/blog/diataxis-a-new-foundation-for-canonical-documentation
- https://github.com/evildmp/diataxis-documentation-framework
- https://docs.readthedocs.io/en/stable/examples.html
- https://about.readthedocs.com/pricing/#/community
- https://about.readthedocs.com/
- https://www.gatsbyjs.com/contributing/docs-contributions/how-to-write-a-how-to-guide/
- https://www.thegooddocsproject.dev/
- https://www.writethedocs.org/
- https://www.writethedocs.org/guide/
- https://gitlab.com/tgdp/templates/-/releases
- https://docs-chronologue.netlify.app/
References
- Reference
Repository
- Home > Ajabbi Research > Library >
- Home > Handbook >
Last Updated
17/05/2025
Designing a help system with Diátaxis
Mike is the inventor and architect of Pipi and the founder of Ajabbi.
What is Diátaxis?
"The Diátaxis approach divides documentation into four distinct content types:
- Tutorials - Lessons that provide a learning experience, taking users step-by-step through hands-on exercises to build skills and familiarity.
- How-To Guides - Practical guides focused on providing the steps to solve real-world problems.
- Reference - Technical descriptions and factual information about the system, APIs, parameters, etc.
- Explanation - Background information and conceptual discussions that provide context and illuminate topics more broadly.
The key premise of Diátaxis is that each content type serves a different user need and has a distinct purpose. Keeping them separated allows the content to be tailored and structured appropriately for that specific goal." - I'd rather be writing Blog
How-To-Guides
"A how-to guide is a recipe that shows the reader how to achieve something.
When the user is getting something done they are at work, applying their knowledge to a real task or problem. Now they need to be shown the key steps to take. What they need is a how-to guide.
Unlike a tutorial, a how-to guide is not responsible for providing a learning experience. It has no obligation to teach. It can assume that the reader has already acquired competence and familiarity with the machinery, its operation, the language used to talk about it and so on. Its obligation is to show a user how to get something done, step-by-step. It’s the obligation of the user to know what they want to get done, and to be able to apply the guide to the needs of their particular situation." - Daniele Procida
Example Outline by Daniele Procida
Overviews and introductory text
The content of a landing page itself should read like an overview.
That is, it should not simply present lists of other content, it should introduce them. Remember that you are always authoring for a human user, not fulfilling the demands of a scheme.
Headings and snippets of introductory text catch the eye and provide context; for example, a how-to landing page:
How to guides
=============
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Installation guides
-------------------
Pellentesque malesuada, ipsum ac mollis pellentesque, risus
nunc ornare odio, et imperdiet dui mi et dui. Phasellus vel
porta turpis. In feugiat ultricies ipsum.
* Local installation |
* Docker | links to
* Virtual machines | the guides
* Linux containers |
Deployment and scaling
-----------------------
Morbi sed scelerisque ligula. In dictum lacus quis felis
facilisisvulputate. Quisque lacinia condimentum ipsum
laoreet tempus.
* Deploy an instance | links to
* Scale your application | the guidesExamples of Help Guides
