Диатаксис — не просто система структурирования документации. Это система понимания ее, направляющая работу авторов документации и определяются качество документации. Однако наиболее очевидно ее применение именно для в стуктуре документации
Из всех наших проблем, которые терзают авторов и сопроводителей документации, проблема структуры отвечает за значительную часть горя, которое они испытывают. На свете есть множество разных архитектур для документации, пытающихся дать решение этой проблемы. Любая последовательная попытка организовать документацию в ясные категории содержания поможет улучшить ее как для авторов, так и для пользователей.
Однако, даже вооружившись полезной структурой, авторы часто находят себя в необходимости написать конкретный материал для документации, который как будто выпадает из имеющейся схемы или пересекает её внутренние границы.
Диатаксис нацелен решить эту проблему предоставляя схему, которая предписывает структуру документации основанную на систематическом описании и анализе потребностей пользователя (а не на характеристиках продукта, который обслуживает документация, или вокруг разных типах вещей, которые автор документации считает важным сказать о продукте)
Диатаксис предоставляет карту отдельных типов документации, а не просто их список, а также определяет эти типы таким образом, что структура всегда естественным образом помогает придавать контенту подходящую форму.
В результате получается документация, которая не только лучше, но и требует меньше усилия для ее создания и поддержания.
Важно понимать, что Диатаксис предназначен для применения в документации к практическому ремеслу, техническому навыку, такому как использование какого-либо продукта. Успешное приложение такого ремесла или навыка включает как теоретическое постижение (знания и понимание), так и способность применять его на практике, работать с инструментами и материалами ремесла.
Диатаксис делит документацию двумя осями знания: теория/практика и приобретение/применение.
Документация таким образом либо содержит теоретическое знание, либо описывает практические действия, а также служит либо нашему приобретению или нашему применению знаний. Исходя из этого строится карта, на которой расположены все четыре формы документации:
Заметное преимущество организации материалов таким образом заключается в том, что она дает и ясные ожидания читателям и указания для авторов. Она проясняет смысл каждой единицы контента, определяет как он должен быть написан и показывать, где его нужно разместить.
Каждая такая единица контента не только выполняет одну определенную работу, но и эта работа ясно отделена и противопоставлена другим функциям документации.
Большинство систем документации и авторов распознают хотя бы некоторые из этих различий и пробуют наблюдать их на практике. Однако, есть некоторая степень сходства между различными формами документации, на карте они — соседи, и есть естественная тенденция к размытию разграничений (что часто можно наблюдать в примерах документации).
- и руководства и инструкции описывают практические шаги
- и инструкции и справочники озабочены применением знания
- и справочники и объяснения содержат теоретическое знание
- и руководства и объяснения связаны с освоением знания
Позволяя этим различиям размываться мы получаем проблемы со структурой. Чаще всего наблюдается полный или частичный коллапс руководств и инструкций друг в друга, в то время как объяснение протекает в руководства и справочники:
Но иногда документация на самом деле выглядит примерно вот так:
Диатакчис создан чтобы помочь документации служить пользователям в из цикле взаимодействия с продуктом.
Эту фразу не стоит понимать слишком буквально. Это не тот случай, когда пользователь обязан встречаться с разными видами документации в порядке инструкции - руководства - справочник - объяснения. На практике реальные пользователи в поисках информации о чем-то конкретном могут прийти в документацию в любом месте и то, что они хотят читать, будет меняться от момента к моменту использования вашей документации.
При этом сама идея цикла потребностей в документации, который проходит через разные фазы, обоснована и соотносится с путем, которым люди в действительности становятся экспертами в выбранном ремесле. Этот порядок имеет смысл и значение.
- фаза, ориентированная на обучение: Мы начинаем с обучения, а обучение навыку означает прямое погружение в практику — под руководством учителя, если нам повезет.
- фаза, ориентированная на задачи: Затем мы хотим применить полученный навык в работе.
- фаза, ориентированная на информацию: Когда работа требует знаний, которых у нас еще нет в голове, она обращает нас к технической справочной информации.
- фаза, ориентированная на объяснения: В конце, вдали от работы, мы осмысляем нашу практику и знания для понимания целого.
А затем все возвращается к началу, возможно, чтобы освоить что-то новое или проникнуть в глубину.
Следующие четыре секции документации поочередно обсуждают каждый из четырех режимов в деталях.