Diátaxis
摘要
Di\xe1taxis 是一套系统化的技术文档编写方法，将文档需求划分为教程、操作指南、技术参考和解释四类，并据此组织内容、风格与架构。该方法轻量易用，不强制实施约束，已被 Vonage、Gatsby、Cloudflare 等团队采用，用于重构内部或开源文档，显著提升了文档的清晰度和可维护性。
荐读理由
读者在构建产品文档时，可直接套用教程、操作指南、技术参考、解释四象限划分内容，避免文档结构混乱，并参考 Cloudflare 等团队的实际应用经验来提升文档对用户和贡献者的可用性。
原文
Diátaxis¶
A systematic approach to technical documentation authoring.
Diátaxis is a way of thinking about and doing documentation.
It prescribes approaches to content, architecture and form that emerge from a systematic approach to understanding the needs of documentation users.
Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs.
Diátaxis solves problems related to documentation content (what to write), style (how to write it) and architecture (how to organise it).
As well as serving the users of documentation, Diátaxis has value for documentation creators and maintainers. It is light-weight, easy to grasp and straightforward to apply. It doesn’t impose implementation constraints. It brings an active principle of quality to documentation that helps maintainers think effectively about their own work.
Contents¶
The best way to get started with Diátaxis is by applying it after reading a brief primer.
These pages will help make immediate, concrete sense of the approach.
This section explores the theory and principles of Diátaxis more deeply, and sets forth the understanding of needs that underpin it.
Diátaxis is proven in practice. Its principles have been adopted successfully in hundreds of documentation projects.
Diátaxis has allowed us to build a high-quality set of internal documentation that our users love, and our contributors love adding to.
—Greg Frileux, Vonage
At Gatsby we recently reorganized our open-source documentation, and the Diátaxis framework was our go-to resource throughout the project. The four quadrants helped us prioritize the user’s goal for each type of documentation. By restructuring our documentation around the Diátaxis framework, we made it easier for users to discover the resources that they need when they need them.
While redesigning the Cloudflare developer docs, Diátaxis became our north star for information architecture. When we weren’t sure where a new piece of content should fit in, we’d consult the framework. Our documentation is now clearer than it’s ever been, both for readers and contributors.
这条对你有帮助吗？