Начните здесь - Диатаксис через пять минут¶

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

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

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

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

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

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

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

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

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

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

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

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

Путеводителем может быть: Как хранить пленку из нитрата целлюлозы (в киносъемке) или Как настроить frame profiling (в программном обеспечении). Или даже: Проблемы с развертыванием.

Справочник¶

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

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

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

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

Объяснения¶

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

Объяснение часто должно вращаться вокруг предмета и приближаться к нему с разных сторон. Он может содержать мнения и принимать перспективы.

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

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

Карта Диатаксиса¶

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

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

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

Компас Diátaxis¶

Как видно из карты:

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

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

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

Но карта не говорит вам, что делать - это ссылка. Чтобы направлять свои действия, вам нужен другой инструмент, в данном случае, своего рода компас Диатаксиса.

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

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

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

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

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

Работающий¶

Для Diátaxis существует очень простой рабочий процесс.

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

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

Вот и все.

Делай то, что тебе нравится¶

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

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

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

Начать¶

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

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