Diátaxis: фреймворк для технической документации, который выбрали Cloudflare и Gatsby
Diátaxis, это способ мышления о технической документации и её написании, представленный на сайте diataxis.fr. Фреймворк утверждает, что у читателей документации есть четыре разных типа потребностей, и под каждую нужна своя форма текста: учебники (tutorials) для того, кто только осваивается, практические руководства (how-to guides) для решения конкретной задачи, техническая справка (reference) для точных данных и объяснение (explanation) для понимания контекста и причин. Diátaxis предлагает не просто писать эти четыре типа текстов по отдельности, а систематически организовывать вокруг них всю структуру документации, так, чтобы архитектура сайта с документацией отражала эту логику потребностей. Фреймворк решает сразу три задачи: что писать (содержание), как писать (стиль) и как это всё организовать (архитектура). Авторы фреймворка подчёркивают, что он лёгкий в применении, не навязывает конкретных технических ограничений и даёт авторам и поддерживающим документацию простой принцип, по которому можно оценивать качество своей работы. На сайте приведены отзывы компаний, применивших Diátaxis на практике. Грег Фрилё (Greg Frileux) из Vonage говорит, что фреймворк помог построить качественную внутреннюю документацию, которую любят и пользователи, и те, кто её пополняет. Компания Gatsby рассказывает, что при реорганизации документации с открытым исходным кодом Diátaxis стал главным ориентиром на протяжении всего проекта: четыре квадранта помогли расставить приоритеты по цели каждого типа документации, и в итоге пользователям стало проще находить нужные материалы. При редизайне документации для разработчиков Cloudflare Diátaxis стал, по словам компании, «северной звездой» для информационной архитектуры, когда возникали сомнения, куда поместить новый материал, команда сверялась с фреймворком, и в результате документация стала понятнее и для читателей, и для тех, кто её пишет. На сайте фреймворка заявлено, что его принципы успешно применены в сотнях проектов документации, хотя конкретный список проектов или точное число не приводятся. Источник не называет автора или создателя Diátaxis и не указывает дату появления фреймворка или отзывов.
Ключевые факты
- Diátaxis делит документацию на четыре формы под четыре разные потребности читателя: учебники, практические руководства, техническая справка, объяснение
- Фреймворк задаёт не только содержание и стиль текста, но и архитектуру всей документации вокруг этих четырёх форм
- Cloudflare использовала Diátaxis как основной ориентир при редизайне документации для разработчиков
- Gatsby реорганизовала документацию с открытым исходным кодом вокруг четырёх квадрантов фреймворка
- На сайте заявлено, что принципы Diátaxis применены в сотнях проектов документации, без указания конкретных примеров или числа
Почему это важно
Техническая документация в большинстве проектов пишется без системного подхода: авторы смешивают в одном тексте вводный учебник, справочные детали и объяснение мотивов, из-за чего читателю трудно найти нужное. Diátaxis предлагает простой принцип: у документации есть ровно четыре типа потребностей читателя, и под каждую нужна своя форма текста и своё место в структуре сайта. Это не новая технология, а способ организации уже существующего контента, поэтому фреймворк может быть применён к любой документации без смены инструментов.
Кому это важно
Фреймворк адресован тем, кто пишет и поддерживает техническую документацию: разработчикам open-source проектов, командам технических писателей и разработчиков в компаниях. Приведённые в источнике примеры, Vonage, Gatsby и Cloudflare, показывают, что Diátaxis применяется как небольшими командами, так и крупными компаниями при редизайне документации для внешних разработчиков.
Как это применить
Источник описывает Diátaxis как лёгкий в применении: фреймворк не навязывает конкретных технических ограничений и не требует смены инструментов документирования. Практическое применение, судя по примерам Gatsby и Cloudflare, выглядит так: существующие материалы документации распределяются по четырём формам (учебники, практические руководства, справка, объяснение), после чего вокруг этого деления перестраивается структура (архитектура) всего раздела документации.
Можно ли доверять
Заявление о том, что принципы Diátaxis «успешно применены в сотнях проектов документации», не подкреплено в источнике списком проектов или точным числом, это утверждение самого сайта фреймворка, без независимой проверки. Три приведённых отзыва (Vonage, Gatsby, Cloudflare), это цитаты компаний-пользователей на самом сайте Diátaxis, а не независимая экспертная оценка. При этом сама популярность обсуждения на Hacker News (271 очко, 38 комментариев) говорит о том, что тема резонирует с сообществом разработчиков документации.
Риски и подводные камни
Источник не называет автора или создателя фреймворка, не указывает дату его появления и не приводит конкретных данных, кроме общих формулировок об успехе внедрения. Как и любой методологический фреймворк, Diátaxis требует времени на пересборку существующей документации под новую структуру, и источник не описывает, сколько усилий это потребовало у Gatsby или Cloudflare.
«Diátaxis позволил нам построить качественную внутреннюю документацию, которую любят наши пользователи и в которую с удовольствием добавляют материалы наши контрибьюторы.»
— Грег Фрилё (Greg Frileux), Vonage