Начните здесь — Diátaxis за пять минут¶

Не нужно читать весь сайт, чтобы понять Diátaxis или начать пользоваться им на практике. Более того, я советую этого не делать. Лучший способ начать работу с Diátaxis — применить его к чему-нибудь, пусть даже совсем небольшому.

Прочитайте эту страницу как краткое введение. В каждом разделе есть ссылки на более подробные материалы — обращайтесь к ним по мере необходимости, когда работаете или обдумываете встретившиеся проблемы с документацией.

Четыре типа документации¶

Основная идея Diátaxis: существуют четыре принципиально разных типа документации, отвечающих четырём разным потребностям. Это учебные руководства, практические руководства, справочник и объяснения. У каждого типа своё назначение и свой способ изложения.

Учебные руководства¶

Учебное руководство — это урок, который шаг за шагом проводит ученика через учебный опыт. Оно всегда практическое: пользователь что-то делает под руководством наставника. Учебное руководство строится вокруг понятной ученику практической ситуации, в которой наставник отвечает за его безопасность и успех.

Урок вождения — хороший пример учебного руководства. Его цель — развить у ученика навыки и уверенность, а не просто добраться из точки А в точку Б. Пример из разработки программ: Создадим простую игру на Python.

Пользователь учится благодаря тому, что делает, а не потому, что кто-то пытается его учить.

Особая трудность документации в том, что наставник неизбежно отсутствует: он не может наблюдать за учеником и исправлять его ошибки. Наставнику приходится находить способ присутствовать посредством одних лишь письменных указаний.

Практические руководства¶

Практическое руководство помогает достичь реальной цели или решить проблему: оно даёт конкретные указания пользователю, оказавшемуся в соответствующей ситуации.

Практическое руководство всегда обращено к уже компетентному пользователю: предполагается, что с его помощью он сможет выполнить свою работу. В отличие от учебного руководства, практическое посвящено работе, а не учёбе.

Примеры практических руководств: Как хранить плёнку на основе нитрата целлюлозы (в кинематографии), Как настроить профилирование кадров (в программном обеспечении) или даже Устранение неполадок при развёртывании.

Справочник¶

Справочные материалы содержат техническое описание — факты, необходимые пользователю для правильных действий: точные, полные и надёжные сведения без отвлекающих подробностей и интерпретаций. Это пропозициональное или теоретическое знание, а не указания к действию.

Как и практическое руководство, справочная документация нужна пользователю во время работы. Предполагается, что он достаточно компетентен, чтобы правильно её истолковать и применить.

Справочный материал нейтрален. Он не зависит от того, что делает пользователь. Одну и ту же морскую карту может использовать и штурман корабля, прокладывающий курс, и судья, ведущий расследование.

По возможности архитектура справочной документации должна, подобно карте, отражать структуру или архитектуру описываемого объекта. Если метод входит в класс, а класс — в определённый модуль, та же связь должна быть видна и в документации.

Объяснения¶

Объяснения дают контекст и необходимые предпосылки. Они помогают понять предмет и увидеть его место в более широкой картине. Объяснения связывают факты и помогают ответить на вопрос почему?

В объяснении нередко приходится рассматривать предмет с разных сторон и подходить к нему с разных направлений. Здесь допустимы мнения и разные точки зрения.

Подобно справочнику, объяснения относятся к области пропозиционального знания, а не действия. Однако, как и учебные руководства, они помогают пользователю учиться, а не работать.

Авторы учебных руководств, желая, чтобы ученики что-то знали, нередко перегружают текст отвлекающими и бесполезными объяснениями. Полезнее дать ученику лишь необходимый минимум («Здесь мы используем HTTPS, потому что так безопаснее»), а для тех, кто будет готов углубиться в тему, добавить ссылку на подробную статью (Безопасная связь с шифрованием HTTPS).

Карта Diátaxis¶

Четыре типа документации и связи между ними можно представить на карте Diátaxis.

Diátaxis — не просто список из четырёх элементов, а их концептуальная система. Карта показывает, как четыре типа документации связаны друг с другом и чем отличаются.

Огромное число проблем с документацией возникает из-за пересечения или размывания обозначенных на карте границ.

Компас Diátaxis¶

Как видно на карте:

учебные и практические руководства относятся к тому, что пользователь делает (действие)
справочник и объяснения относятся к тому, что пользователь знает (познание)

С другой стороны:

учебные руководства и объяснения служат освоению навыка (учёбе пользователя)
практические руководства и справочник служат применению навыка (работе пользователя)

Но карта не говорит, что делать: сама она относится к справочному типу. Чтобы направлять действия, нужен другой инструмент — в данном случае своего рода компас Diátaxis.

Компас полезен двумя разными способами.

При создании документации он помогает прояснить собственные намерения и убедиться, что вы действительно делаете то, что намеревались.

При анализе документации он помогает понять, что в ней происходит, и делает проблемы заметнее.

Компас не так эффектен, как карта, но, когда вы ломаете голову над проблемой с документацией, именно он помогает двигаться дальше.

Если материал…	…и отвечает потребности пользователя в…	…то он относится к…
даёт информацию для действия	освоении навыка	учебному руководству
даёт информацию для действия	применении навыка	практическому руководству
даёт информацию для познания	применении навыка	справочнику
даёт информацию для познания	освоении навыка	объяснениям

Работа¶

У Diátaxis очень простой рабочий процесс.

Рассмотрите то, что прямо сейчас перед вами в документации (если вы ещё не начали работу, перед вами может не быть вообще ничего).
Спросите себя: можно ли это как-нибудь улучшить?
Выберите одно изменение, которое можно сделать прямо сейчас и которое, пусть даже совсем немного, улучшит документацию.
Сделайте это.

А затем повторите.

Вот и все.

Используйте как хотите¶

Вы можете использовать Diátaxis как хотите. Необязательно верить в него, и экзамена не будет. Это исключительно прагматический подход. Я считаю его верным, но важно прежде всего то, что он действительно помогает людям создавать более качественную документацию. Если найдёте в нём ценную идею или наблюдение, берите их на вооружение.

Вокруг Diátaxis выстроена подробно разработанная теория, но вам необязательно с ней соглашаться или даже читать о ней. Diátaxis не обязывает пройти весь путь до конца.

Прямо сейчас можно сделать всего одно изменение. Даже если после этого вы никогда больше ничего не предпримете, документация всё равно станет лучше хотя бы в одном месте. (На практике каждое действие будет подсказывать следующее — останется лишь продолжать.)

Приступайте¶

Теперь вы прочитали всё необходимое, чтобы начать работать с Diátaxis.

Если хотите, читайте дальше — со временем это, вероятно, стоит сделать. Но рекомендации сайта принесут больше всего пользы, когда вы обратитесь к ним с конкретной проблемой или вопросом. Именно тогда Diátaxis оживает.