Diátaxis¶
Системный подход к созданию технической документации.
Diátaxis — это способ мыслить о документации и создавать её.
Diátaxis предлагает подходы к содержанию, архитектуре и форме документации, основанные на системном понимании потребностей её пользователей.
Diátaxis выделяет четыре разные потребности и четыре соответствующие им формы документации: учебные руководства, практические руководства, технический справочник и объяснения. Подход устанавливает системную связь между ними и предлагает строить документацию в соответствии со структурой этих потребностей.
Diátaxis решает проблемы содержания документации (что писать), стиля (как писать) и архитектуры (как организовать материал).
Diátaxis полезен не только пользователям документации, но и тем, кто её создаёт и поддерживает. Он не требует сложного внедрения, его легко понять и применить. Подход не навязывает способ реализации и вводит действенный принцип качества, который помогает авторам осмысленно оценивать собственную работу.
Содержание¶
Лучший способ познакомиться с Diátaxis — прочитать краткое введение и сразу применить подход на практике.
Эти страницы помогут быстро составить конкретное представление о подходе.
В этом разделе подробнее рассматриваются теория и принципы Diátaxis, а также представление о потребностях, на которых основан подход.
Diátaxis проверен на практике. Его принципы были успешно использованы в сотнях проектов по созданию документации.
Благодаря Diátaxis мы создали качественный комплект внутренней документации: пользователям нравится ею пользоваться, а участникам проекта — дополнять её.
—Грег Фриле, Vonage
Недавно мы в Gatsby перестроили документацию нашего проекта с открытым исходным кодом, и на протяжении всей работы Diátaxis служил нам главным ориентиром. Четыре квадранта помогли определить главную цель пользователя для каждого типа документации. Организовав документацию по модели Diátaxis, мы помогли пользователям находить нужные материалы именно тогда, когда они нужны.
Во время переработки документации Cloudflare для разработчиков Diátaxis стал нашей путеводной звездой в информационной архитектуре. Если мы сомневались, где разместить новый материал, то сверялись с этой моделью. Теперь наша документация понятнее, чем когда-либо прежде, и для читателей, и для участников проекта.