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