Boost Your Growth with Great Documentation: Diataxis Explained

Technical documentation can often feel like a tangled mess, frustrating for both users and creators. As software projects grow in size and complexity, the need for clear, structured, and accessible documentation becomes paramount. Enter the Diataxis Framework, a modern approach to technical documentation that is gaining widespread adoption, from developer-centric AI tools like LangChain to Web3 infrastructure projects like StreamingFast.

In this blog post, we'll explore what the Diataxis Framework is, why it's being adopted by popular software and open-source projects alike, and how teams can transition their current documentation to align with this powerful model.

1. What is the Diataxis Framework?

The Diataxis Framework is a systematic and structured approach to organizing technical documentation, designed by Daniele Procida. It breaks documentation into four distinct types, each serving a unique user need:

• Tutorials: Learning-oriented guides that take users step-by-step through a process to achieve a specific goal. They are particularly helpful for beginners.
• How-To Guides: Goal-oriented instructions for solving specific problems. These guides are task-focused and assume users have some baseline knowledge.
• Reference: Information-oriented documentation that provides factual details like API references, configuration options, or technical specifications. It's designed for quick lookup.
• Explanation: Understanding-oriented content that provides deeper context or rationale, helping users understand the "why" behind a feature or process.

This framework helps teams deliver documentation that is easy to navigate and supports users at different stages of their learning journey, whether they're brand new or deeply familiar with the project.

2. Why Are Popular Open Source Projects Adopting Diataxis?

Several factors explain the growing popularity of the Diataxis Framework across Web2 and Web3 projects, including:

2.1. Clear Structure for Diverse Users

In open-source ecosystems, communities are often highly diverse. New contributors, experienced developers, and casual users all interact with a project in different ways. Diataxis helps segment documentation in a way that serves all parties by offering:

• Tutorials for new users to onboard quickly
• How-To Guides for intermediate users solving specific problems
• Reference materials for experts needing precise information
• Explanations to provide deeper understanding

By structuring documentation with Diataxis, projects can cater to all user groups effectively.

2.2. Facilitating Contributor Onboarding

Many Web2 and Web3 open-source projects rely on global contributors, making effective documentation crucial for scaling. Diataxis streamlines onboarding with well-organized tutorials and clear task-based guides, helping new developers become productive faster.

2.3. Improving User Retention

Open-source projects often face the challenge of retaining users and contributors after the initial interest fades. Documentation that covers both the how and the why of a project—through How-To Guides and Explanations—can help users feel more confident in their understanding, leading to deeper engagement and higher retention.

2.4. Aligning with Agile and Decentralized Workflows

Many Web3 projects are decentralized, with contributions coming from different teams or even anonymous developers. Diataxis provides a clear and scalable documentation structure that teams can follow regardless of their geographical or organizational context. The framework’s modularity also supports agile workflows, where quick updates and new features need to be documented in a consistent, accessible manner.

2.5. Better Searchability and SEO

In the open-source world, users often arrive at documentation through search engines. Diataxis ensures that documentation is broken down into clear sections, improving searchability. For example, a user looking for a specific API reference can find it quickly without wading through tutorials or how-to content.

3. How to Convert Your Existing Documentation to Diataxis

Implementing the Diataxis Framework in your project’s documentation may seem daunting at first, but it’s a straightforward process when broken down into manageable steps. Here’s a roadmap for teams looking to transition:

3.1. Audit Your Current Documentation

Start by creating an inventory of your existing documentation. Identify the different types of content you currently have, such as installation guides, feature explanations, or API references. You might find that some documents already align with Diataxis categories, while others are mixed or incomplete.

3.2. Map Content to Diataxis Categories

Once you've audited your documentation, classify each piece into one of the four Diataxis categories:

• Tutorials: Any existing step-by-step guides that show users how to achieve a specific goal.
• How-To Guides: Documents that provide solutions to specific problems, such as “How to Set Up X” or “How to Use Feature Y.”
• Reference: API documentation, configuration options, and technical specifications that are meant for quick look-up.
• Explanations: Articles that delve into the reasoning or theory behind certain features or architectural decisions.

3.3. Identify Gaps and Redundancies

You’ll likely find gaps where critical content is missing, as well as redundancies where content is too long or overlaps multiple categories. For example, a “Getting Started” guide might mix conceptual overviews with installation steps—these should be separated into Explanations and Tutorials.

3.4. Restructure Content for Clarity

Reorganize your documentation to align with the Diataxis categories. You may need to break larger documents into smaller, more focused pieces. Ensure that each category is presented consistently, with clear labeling and navigation, so users can easily find what they’re looking for.

3.5. Update and Maintain

Documentation is an ongoing process. Ensure that your team is aligned on the principles of Diataxis for future contributions. New features should always have corresponding content in each of the Diataxis categories—Tutorials for onboarding, How-To Guides for specific use cases, Reference for technical details, and Explanations for deeper insights.

3.6. Gather Feedback and Iterate

Once your documentation is live, gather feedback from users and contributors. Are they finding what they need? Are certain types of documents being overlooked or hard to navigate? Use this feedback to continuously improve and refine your documentation.

4. Using Katara to quickly adopt Diataxis

Katara is an agentic workflow automation platform for DevX teams.

4.1 Katara's Diataxis Agent Workflow

Katara has built an AI-agent based workflow that helps accelerate the adoption of the Diataxis framework. The solution includes a content classifier that can quickly map your existing content to the most relevant Diataxis category. Next, it can identify gaps and overlaps potentially splicing up content to better fit to the framework, after that Katara leverages Generative AI to restructure and/or rewrite section or entire articles to fill previously identified gaps. Additionally, you can leverage other AI-agents that can perform tasks like topical and/or keyword hyperlinking to improve in-document navigation, or apply a specific style guide. Finally, use Katara to monitor new content publishing to help keep you in framework compliance. Every step includes an optional human-in-the-loop circuit to provide the agents feedback or directly edit AI generated content. You are fully in control. Interested? Email diataxis@katara.ai for early access to this workflow!

Additionally, you can leverage other AI-agents that can perform tasks like topical and/or keyword hyperlinking to improve in-document navigation, or apply a specific style guide. Finally, use Katara to monitor new content publishing to help keep you in framework compliance. Every step includes an optional human-in-the-loop circuit to provide the agents feedback or directly edit AI generated content. You are fully in control.

Conclusion

The Diataxis Framework is quickly becoming the go-to method for structuring documentation in both Web2 and Web3 open-source projects. By offering a clear, user-focused framework, Diataxis ensures that documentation can grow with the project, serving beginners, experts, and everyone in between. As more projects adopt this model, it’s transforming the way teams approach documentation, making it more accessible, scalable, and useful for developers worldwide.

If your project’s documentation feels disorganized or incomplete, consider implementing the Diataxis Framework via Katara—it might just be the structure you need to take your documentation to the next level.