Документация и объяснения — недооценённая штука. Поэтому часто документация вещей вокруг нас бывает непонятна. Я уже писал про это на примере фотоаппаратов.

А тут некие ребята написали про Теорию Документации в которой попытались объяснить, почему же документация часто не помогает. Согласно этой системе есть четыре разных типа документации. У них разная структура и цели.

• Туториалы (tutorials). Фокус на быстрый старт и обучение тех, кто только знакомится с продуктом.
• Гайды (how-to guides). Фокус на решение проблем или достижение конкретных целей.
• Технические референсы (technical reference). Фокус на получение информации и необходимых деталей.
• Объяснения (explanations). Фокус на глубокое понимание предмета и контекста.

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

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

Задача туториала — показать как достичь чего-то интересного (и мы выбираем, что будет этим интересным). Это нормально, если в процессе не будет понятна глубинная суть и или какие-то отдельные моменты (“а зачем вот так вот?”). Важно, что повторив эти шаги, человек получит конкретный результат. Результат должен быть достижим для новичка (при условии выполнения всех шагов) и значим для него/нее.

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

Что еще важно для туториала:

• Лучше предложить сразу что-то сделать, чем долго описывать и объяснять. В туториале: деланье > объяснение. Конкретные шаги лучше чем описание абстракций.
• Шаги должны работать для всех.
• Результат должен быть виден сразу.
• Фокус только на выбранной цели, все остальное можно рассказать и показать позже.

Гайды и How-to
How-to — набор шагов для решения конкретной реальной проблемы или достижения какой-то определенной цели. Цель для гайдов очень важна.

Аналогия с готовкой еды: рецепты. Конкретный набор шагов и описание того, что надо сделать, чтобы получить определенное блюдо.

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

Что еще важно для how-to:

• Конкретный набор шагов
• Фокус на практический результат: решение проблемы, достижение цели.
• Не стоит объяснять абстрактные концепты, лучше дать сразу решение. Если концепты важны — на них просто стоит дать ссылку.
• Если решить проблему можно несколькими путями — стоит описать их все.
• How-to может быть менее детален чем туториал — пользователь тут уже чуть больше знаком с продуктом.
• Название должно сразу объяснять какую проблему мы решаем или какой цели хотим достичь (“How to…”).

Технические референсы
Референс — подробное описание внутренних штук какой-то системы и как что там всё внутри работает. Главная цель референса — дать информацию.

Аналогия с готовкой еды: статья в энциклопедии про какой-то ингредиент, например про картошку или черный перец.

Референс может описать как что-то работает, но его главная цель не решить проблему или достичь какой-то цели, а дать информацию о том, что и как работает.

Что еще важно для референсов:

• Предсказуемая структура у всех частей.
• Фокус на описание “как все устроено”.

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

Аналогия с готовкой еды: книга о готовке еды и о еде. Например, почему мы едим то, что едим. Или что ели в прошлом и почему. Анализ еды с точки зрении науки и так далее.

Что еще важно для объяснений:

• У объяснений нет конкретной строго определенной цели. Это решение автора — что считать важным.
• Хорошо давать контекст и подоплёку решений. Почему выбрано такое решение, а не альтернативы.
• Объяснения рассказывают о том, что не рассказывают другие части документации.
• Часто объяснения не выделяются в отдельную секцию, а интегрируются с другими секциями.

Это очень интересный подход. Если применить его к разный документации, например к документации бытовых приборов, то заметно чего не хватает. Как правило в документации есть много референсов (“объясним тебе в деталях, что делает каждая кнопка. Видишь кнопку Стоп? Она делает стоп.”) и немного гайдов (“а вот, что надо сделать, если произошла ошибка A23-71”). Но очень редко встречаются хорошие туториалы: “вот ты купил эту штуку — как максимально быстро ее запустить, чтобы увидеть как она сделает что-то полезное”. Да, в продуктах типа “чайника” или “фена” можно и без этого (и то — не всегда), но чем сложней и непривычней продукт для пользователя — тем это важнее.