Diátaxis Framework¶
The Diátaxis framework is a systematic approach to technical documentation that was developed to address the challenge of structuring documentation in a clear and logical way. The framework consists of four distinct modes of documentation, each of which serves a distinct user need and requires a unique approach to creation.
| Mode | Focus | Purpose |
|---|---|---|
| Tutorials | Learning-oriented | Used to teach new users how to use a product or technology. |
| How-To Guides | Problem-oriented | Provide solutions to specific problems or use cases. |
| Technical Reference | Information-oriented | Provides detailed information on the features, functions, and capabilities of a product or technology. |
| Explanation | Understanding-oriented | Provides conceptual information and context to help users understand a product or technology. |
By adopting the Diátaxis framework, technical writers can ensure that their documentation is tailored to the user's needs and provides the information they need in a clear and concise manner. The framework has gained widespread adoption in the technical writing community and is considered a best practice for creating effective technical documentation.
Tutorials¶
Tutorials walk users through a process or task step-by-step. They should be structured in a clear and logical way, with each step building on the previous one. Tutorials should also include visuals and examples to help users understand the process.
Example: A tutorial on how to create a new user account in a software application.
Remember
- Clearly state the learning objective
- Break down the task into clear and concise steps
- Use images, diagrams, and examples to aid understanding
- Provide feedback and reinforcement to encourage learning
How-To Guides¶
How-to guides provide solutions to specific problems or use cases. They should be focused and concise, providing clear and actionable steps to solve the problem.
Example: A how-to guide on how to troubleshoot a connectivity issue with a networking device.
Remember
- Clearly state the problem or use case
- Provide a clear and concise solution
- Use screenshots or other visuals to help users understand the solution
- Test the solution to ensure it works as expected
Technical Reference¶
Technical reference documentation provides detailed information on the features, functions, and capabilities of a product or technology. It should be well-organized and easy to navigate, with a clear and concise description of each feature or function.
Example: Technical reference documentation for a software library, detailing each of its APIs and functions.
Remember
- Clearly define each feature or function
- Provide detailed information on each feature or function, including syntax, parameters, and return values
- Organize the information in a clear and logical manner
- Provide examples of how to use each feature or function
Explanation¶
Explanation provides conceptual information and context to help users understand a product or technology. It should be clear and concise, providing context and explanation in a way that is easy to understand.
Example: An explanation of the importance of project documentation and an overview of the Diátaxis framework.
Remember
- Provide high-level overviews of the product or technology
- Provide conceptual information and context to help users understand the product or technology
- Explain why the product or technology is important and how it fits into the broader technology landscape
- Use analogies or other relatable examples to aid understanding