Карта

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

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

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

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

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

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

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

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

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

Ожидания и руководство

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

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

Каждая часть контента имеет не только одну конкретную работу, но и четко отличается от других функций документации.

пятно

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

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

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

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

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

---

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

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

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

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

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

• целенаправленный этап: Мы хотим, чтобы этот навык работал.

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

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

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