Карта

Одна из причин эффективности Diátaxis как руководства по организации документации — описание двумерной структуры, а не списка.

Типы документации определены так, что сама структура естественным образом направляет и формирует содержащийся в ней материал.

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

Проблема структуры

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

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

Даже для одного набора документов такой подход редко оказывается успешным. В целом портфеле он приводит к вопиющей непоследовательности. Гораздо лучше принять схему, которая отвечает на вопрос: как организовать документацию в общем случае?

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

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

Ожидания и ориентиры

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

	Учебные руководства	Практические руководства	Справочник	Объяснения
что они делают	знакомят, обучают, ведут	направляют	излагают факты, описывают, информируют	объясняют, проясняют, обсуждают
отвечают на вопрос	«Можете научить меня…?»	«Как мне…?»	«Что такое…?»	«Почему…?»
ориентированы на	обучение	цели	информацию	понимание
назначение	создать условия для обучения	помочь достичь конкретной цели	описать устройство системы	прояснить тему
форма	урок	последовательность шагов	сухое описание	развёрнутое объяснение
аналогия	обучение ребёнка приготовлению пищи	рецепт из поваренной книги	сведения на упаковке продукта	статья о социальной истории кулинарии

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

Размывание границ

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

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

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

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

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

---

Путешествие по карте

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

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

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

• этап, ориентированный на обучение: Сначала мы учимся, а учиться навыку — значит сразу погрузиться в практику, если повезёт — под руководством наставника.

• этап, ориентированный на цель: Затем нам хочется применить навык.

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

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

Затем мы возвращаемся к началу — возможно, чтобы освоить что-то новое или углубить свои знания.