Документация и объяснения — недооцененная штука. Поэтому часто документация вещей вокруг нас бывает непонятна.
А тут некие ребята написали про Теорию Документации в которой попытались объяснить, почему же документация часто не помогает: https://documentation.divio.com/
Согласно этой системе есть четыре разных типа документации. У них разная структура и цели.
- Туториалы (tutorials). Фокус на быстрый старт и обучение тех, кто только знакомится с продуктом.
- Гайды (how-to guides). Фокус на решение проблем или достижение конкретых целей.
- Технические референсы (technical reference). Фокус на получение информации и необходимых деталей.
- Объяснения (explanations). Фокус на глубокое понимание предмета и контекста.
Туториалы
Туториал — набор шагов для достижения какого-то первого значимого результата. Цель: помочь новичку сделать первый шаг, показать, что она/она может с помощью продукта добиться чего-то значимого и полезного.
Аналогия с готовкой еды: обучение ребенка готовке. Не важно ЧТО вы готовите, важно, чтобы ребенок получил удовольствие, приобрел уверенность, что он может это сделать и захотел повторить.
Задача туториала — показать как достичь чего-то интересного (и мы выбираем, что будет этим интересным). Это нормально, если в процессе не будет понятна глубинная суть и или какие-то отдельные моменты ("а зачем вот так вот?"). Важно, что повторив эти шаги, человек получит конкретный результат. Результат достижимый для новичка (при условии выполнении шагов) и значим для него/нее.
Туториалы помогают новичкам начать и дают им мотивацию продолжать разбираться. Они должны быть просты, подробны и (повторю еще раз, так как это важно) приводить к значимому первому результату.
Что еще важно для туториала:
— Лучше предложит сделать, чем долго описывать и объяснять. В туториале: деланье > объяснение. Конкретные шаги лучше чем описание абстракций.
— Шаги должны работать для всех.
— Результат должен быть виден сразу.
— Фокус только на выбранной цели, все остальное можно рассказать и показать позже.
Гайды и How-to
How-to — набор шагов для решения конкретной реальной проблемы или достижения какой-то определенной цели. Цель для гайдов очень важна.
Аналогия с готовкой еды: рецепты. Конкретный набор шагов и описание того, что надо сделать, чтобы получить определенное блюдо.
Отличие от туториалов в том, что в туториале мы выбираем цель за пользователя. А в гайдах — пользователь сам знает, что это за цель или проблема. Более того, сама формулировка вопроса от пользователя уже требует некоторого опыта с продуктом.
Что еще важно для how-to:
- Конкретный набор шагов
- Фокус на практический результат: решение проблемы, достижение цели.
- Не стоит объяснять абстрактные концепты, лучше дать сразу решение. Если концепты важны — на них просто стоит дать ссылку.
- Если решить проблему можно несколькими путями — стоит описать их все.
- How-to может быть менее детален чем туториал — пользователь тут уже чуть больше знаком с продуктом.
- Название должно сразу объяснять какую проблему мы решаем или какой цели хотим достичь
Технические референсы
Референс — подробное описание внутренних штук какой-то системы и как что там все внутри работает. Главная цель референса — дать информацию.
Аналогия с готовкой еды: статья в энциклопедии про какой-то ингредиент, например картошку или черный перец.
Референс может описать как что-то работает, но его главная цель не решить проблему или достичь какой-то цели, а дать информацию о том, что и как работает.
Что еще важно для референсов:
- Предсказуемая структура у всех частей
- Фокус на описание "как все устроено"
Объяснения
Объяснения помогают понять какую-то область, дают понимание контекста и выбранных решений. "Вот почему всё так".
Аналогия с готовкой еды: книга о готовке еды и о еде. Например почему мы едим то, что едим. Или что ели в прошлом и почему. Анализ еды с точки зрении науки и так далее.
Что еще важно для объяснений:
- У объяснений нет конкретной строго определенной цели. Это решение автора — что считать важным.
- Хорошо давать контекст и подоплёку решений. Почему выбрано такое решение, а не альтернативы.
- Объяснения рассказывают о том, что не рассказывают другие части документации.
- Часто объяснения не выделяются в отдельную секцию, а интегрируются с другими секциями.
Это очень интересный подход. Если применить его к разный документации, например к документации бытовых приборов, то заметно чего не хватает. Как правило в документации есть много референсов ("объясним тебе в деталях, что делает каждая кнопка. Видишь кнопку Стоп? Она делает стоп.") и немного гайдов ("а вот, что надо сделать, если произошла ошибка A23"). Но очень редко встречаются хорошие туториалы: "вот ты купил эту штуку — как максимально быстро ее запустить, чтобы увидеть как она сделает что-то полезное". Да, в продуктах типа "чайника" или "фена" можно и без этого (и то — не всегда), но чем сложней и непривычней продукт для пользователя — там это важнее.