Это первая статья в корпоративном блоге компании documentat.io. Мы занимаемся заказной разработкой технической документации и помогаем компаниям настраивать процессы документирования.

Многие разработчики сталкиваются с тем, что писать и поддерживать документацию трудно: непонятно с чего начать, что и куда написать, и как это безобразие дополнять по мере развития проекта. Часто в результате получается документация, которую тяжело читать. А значит пользователи читать её и не будут, вместо этого будут действовать методом проб и ошибок или дёргать техподдержку. И это в лучшем случае. В худшем — откажутся от использования продукта. В итоге пострадают все: и разработчики, и пользователи, и техподдержка, и бизнес.

Решить эту проблему можно двумя способами:

• Завести своего собственного технического писателя или нанять уже готовую команду на аутстаффинг.

• Сделать так, чтобы разработчикам стало проще писать документацию.

Рассмотрим второй вариант. Чтобы писать документацию стало проще, нужно продумать её структуру  — разделить документацию на жанры и наполнять каждый раздел в строгом соответствии с его жанром. Этот подход придуман давно и встречается в различных книгах для техписателей в разных вариациях. Наиболее современным и эффективным, на наш взгляд, является Diátaxis.

В этой статье разберёмся:

• Как устроен Diátaxis и чем он вам поможет?

• Чем жанры отличаются друг от друга?

• На что обратить внимание при работе с каждым из жанров?

Также мы взглянем на несколько примеров применения и неприменения этого подхода.

Что такое Diátaxis?

Diátaxis — это подход к разработке документации, при котором каждый раздел документации относится к одному из жанров:

• Описательные:

  • Концепции (concepts, explanations) — описывают какое-то понятие, концепцию или объект, составляющий систему. Например: для чего нужен продукт, какие модули его составляют, как работает отдельный модуль, какие интерфейсы доступны и т. д.

  • Справочники (references) — полный список однородных компонентов продукта. Это могут быть: ключи командной строки, элементы синтаксиса, настройки, параметры, запросы к API, коды ошибок и т. п.

• Директивные:

  • Туториалы (tutorials) — обучающие задачи с пошаговым решением. Проходя туториал, пользователь на конкретных примерах разбирается, как работает система. Туториалы нацелены на то, чтобы научить пользователя работать с продуктом. Решение поставленной задачи является не самоцелью туториала, а средством обучения пользователя.

  • Гайды (howto guides) — пошаговые инструкции по работе с продуктом. Гайды призваны помочь пользователю решить задачу, с которой он столкнулся в ходе работы. В отличие от туториалов гайды дают универсальные решения, не привязанные к конкретным примерам.

Почему Diátaxis хорош?

Он реально упрощает жизнь!

Он упрощает жизнь пользователям

Пользователь никогда не читает документацию от корки до корки. На разных этапах знакомства с продуктом пользователь решает с помощью документации разные задачи:

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

• Настроить продукт и потестировать на практике, чтобы научиться с ним работать.

• Найти инструкцию по решению задачи, возникшей при работе с продуктом.

• Понять, как именно работает тот или иной элемент продукта, например, команда консоли или вызов API.

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

Он упрощает жизнь вам

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

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

Жанры документации

Описательные жанры

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

Концепции

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

• Какие проблемы решает продукт?

• Из чего он состоит?

• Какие принципы лежат в основе продукта и его элементов?

• Как работает каждая составляющая и как они связаны между собой?

• Какие ограничения есть у продукта?

Это не обязательный и не полный список, здесь есть пространство для творчества.

Но есть и список того, что писать в концепциях не следует:

• Не пытайтесь рекламировать продукт.

• Не вдавайтесь в низкоуровневые технические подробности. Для них предусмотрены справочники. Проще говоря: блок-схеме — да, примеру консольной команды — нет.

• Не приводите никаких инструкций. Здесь вы рассказываете читателю что есть. А что с этим делать, он узнает из гайдов и туториалов. Допустимо дать на них ссылки в конце подраздела.

Примеры хороших концепций:

• Explanations в Anbox Cloud.

• Концепция Promise в JavaScript.

• Концепция оспаривания платежей в Stripe.

• Набор концепций, связанных с Managed Clickhouse в Yandex.Cloud.

Справочники

Справочники перечисляют и описывают функциональные составляющие продукта — ключи командной строки, элементы синтаксиса, настройки, параметры, запросы к API, коды ошибок и т. п. К жанру справочников относятся справочники API, выгрузки Javadoc, перечни параметров у CLI-утилит, диаграммы классов в программной системе.

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

• Упорядоченный и полный список элементов.

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

• Самодостаточное описание каждого элемента.

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

• Иллюстративные примеры использования элемента.

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

Примеры хороших справочников:

• Список SQL-команд PostgreSQL.

• Список встроенных объектов JavaScript.

• Список API-методов для Yandex Managed Service for Clickhouse.

Справочник — это первое, а иногда единственное, что приходит в голову большинства разработчиков, когда речь заходит о документации. Разработчик уже знает, как работает его продукт и как им пользоваться. Поэтому ему кажется, что мелкие технические подробности — это всё, чего не хватает пользователю. Но это не так.

Нельзя научиться пользоваться продуктом, читая список команд, как нельзя выучить английский, читая англо-русский словарь. Эффективное обучение работе с продуктом строится от решения простых учебных заданий уровня «Hello, World»  к реальным задачам. Выстроить такое обучение в документации вам помогут разделы, написанные в директивном жанре, — туториалы и гайды.

Директивные жанры

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

Гайды

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

Чтобы у вас получился хороший гайд:

• Поместите в название решаемую задачу.

  Так пользователь быстрее найдёт нужный гайд. Идеально, если название начинается со слова как.

• Начните с разумной отправной точки.

  Если вы пишете о том, как написать на Python обёртку для ChatGPT API, не нужно начинать гайд с установки Python. Примерно представьте себе, на каком уровне знакомства с продуктом будет находиться пользователь, когда приступит к решению задачи. И начинайте отсюда.

• Описывайте решение одной проблемы.

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

А вот чего делать не стоит:

• Не привязывайте гайд к какому-то определенному набору данных.

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

• Не делайте лишних отступлений.

  Гайд должен приводить из отправной точки к результату как можно быстрее, поэтому:

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

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

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

Примеры хороших гайдов:

• Работа с Anbox Cloud.

• Загрузка объектов в Amazon S3.

• Создание кластера MySQL в Yandex.Cloud.

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

Туториалы

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

Чтобы написать хороший туториал:

• Чётко сформулируйте задачу, которая будет решена при прохождении туториала.

• Явно задайте начальные условия.

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

• Приведите конкретные наборы данных, примеры кода и команд для выполнения задачи.

• Придерживайтесь пошаговой структуры.

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

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

Примеры хороших туториалов:

• Пишем первое приложение на Django.

• Настраиваем статический сайт на Amazon S3.

• Пишем первое приложение на GTK-Fortran.

Неудачные примеры

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

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

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

• Все начинающие разработчики изучают Git. При этом информацию они обычно черпают из гайдов в интернете или от старших коллег. Вряд ли для понимания основ работы с Git новичок станет пользоваться официальным gittutorial. И вот почему:

  • Нет конкретных примеров файлов и каталогов, которые пользователь создаёт.

  • Нет начальных условий и пошаговой структуры.

  • Как следствие предыдущих пунктов — нет осязаемых результатов.

  • Различные способы выполнить одно действие и концептуальные отступления лишь сбивают с толку.

  Сравните, насколько легче воспринимается сторонний туториал по Git.

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

Заключение

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

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

При этом не стоит воспринимать предложенный набор жанров и их интерпретацию, как строгий стандарт. Только вы можете определить, какой объём и содержание документации необходимы вашему продукту.

Чтобы документация работала эффективно, и это не был Diátaxis ради Diátaxis, используйте следующий подход:

1. Возьмите Diátaxis за основу вашего внутрикомандного docing standard (это как coding standard, только docing).

2. Видоизмените предложенную парадигму, если считаете нужным.

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

   Также вы можете по своему усмотрению опустить какие-то жанры из набора, например, если считаете, что продукт достаточно простой и можно обойтись без туториалов. Ещё раз подчеркнём, главное — не смешивайте разные жанры в одном разделе.

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

Мы надеемся, что статья была полезной и изложенная парадигма поможет вам в разработке документации. Пишите в комментариях, какие подходы к структуре документации используете вы. А если вы вообще не очень любите писать документацию, доверьте это нам — обращайтесь в documentat.io!

Авторы: Семён Факторович, Костя Макушев

Редактор: Ната Мелихова