Выпуск #10. Обзор Diataxis (системный подход к созданию технической документации)

Опубликовано 26.10.2023

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

Полезные ссылки

diataxis.fr

Daniele Procida

Запись вебинара “Introducing the Diátaxis Approach to Technical Documentation”

Слушайте подкаст на любимых платформах

Поделитесь подкастом с друзьями и коллегами

---

Расшифровка выпуска

00:00 - 01:56 Приветствие

Добро пожаловать в подкаст технического коммуникатора Техкомпод!

Меня зовут Владимир Юсупов. Я - технический коммуникатор и, по совместительству, ведущий данного подкаста.

На календаре 26 октября 2023 года.

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

Напомню, что одна из основных тем подкаста - это разработка технической документации. Вчера принял участие в вебинаре Даниэле Просида (Daniele Procida) - создателя Diátaxis - подхода к организации технической документации.

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

А пока послушайте мою вольную интерпретацию Diátaxis.

01:57 - 02:54 Концепция Diátaxis

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

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

02:55 - 03:52 Обзор типов документации в Diátaxis

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

• Туториалы (tutorials) или обучающие материалы для описания пошаговых практических действий, в ходе выполнения которых происходит знакомство с продуктом.
• Руководства (how-to guides) или пошаговые инструкции, которые ориентированы на решение конкретных задач при работе с продуктом.
• Справочники (references), которые используются для краткого и упорядоченного описания компонентов продукта.
• Объяснение (explanation) - это верхнеуровневая информация, которая дает общее представление о продукте в целом.

03:53 - 05:10 Взаимосвязь типов документации в Diátaxis

Кстати, интересна также взаимосвязь этих четырех типов.

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

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

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

05:11 - 06:12 Туториалы

Теперь немного подробнее о каждом из озвученных типов.

Начнем с туториалов.

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

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

06:13 - 07:08 Руководства

Далее идут руководства или как мы часто их называем “хаутушки”.

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

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

07:09 - 08:04 Справочники

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

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

08:05 - 09:26 Объяснение

И последний тип документации в парадигме Diátaxis - объяснение.

Хотя всё-таки более правильно с него начинать. Но в контексте ознакомления и просто перечисления существующих типов порядок не столь важен.

Итак, объяснение - верхнеуровневая информация, которая дает общее представление о продукте в целом. С помощью документации данного типа пользователь просто проясняет свое понимание объекта документирования.

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

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

09:27 - 10:57 Заключение

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

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

Спасибо, что прослушали этот выпуск от начала до конца. Если у Вас возникли вопросы, замечания или предложения, пишите мне. Заходите на мой сайт techwritex.ru. Там я периодически пишу заметки по техписьму и коммуникациям. И конечно же подписывайтесь на подкаст.

На этом у меня всё. До встречи!

С Вами был Владимир Юсупов. Подкаст технического коммуникатора Техкомпод.

Пока!