Parawriter

Недавно мне довелось разрабатывать пользовательскую документацию сразу к нескольким внутренним продуктам.

Это был интересный опыт: одно дело просто написать какую-нибудь доку (этим мы и так занимаемся каждый день), и совсем другое — разработать пользовательскую продуктовую документацию.

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

Как понять, что именно должно входить в этот туториал? Насколько подробно писать инструкции? Как глубоко погружаться в техническую реализацию функциональности программы? Можно ли упустить что-то из виду?

Попробую что-нибудь посоветовать на основе моего недавнего, но довольно успешного опыта.

1. Определите целевую аудиторию документации.

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

Нашими продуктами пользуются наши же коллеги: разработчики, sre и devops-инженеры, все свои в доску ребята, которым можно не разжёвывать некоторые технические аспекты и не объяснять общеупотребимые термины.

2. Определите главное назначение продукта, который вы описываете.

Постарайтесь ответить как можно подробнее: для чего предназначена программа и что с её помощью можно делать?

Я выписал список всех основных функций программы — описание работы с этими функциями и будет основой моей доки.

3. Составьте структурный макет документации.

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

Как правильно собрать этот каркас, чтобы получить полноценную документацию и при этом не наплодить лишних сущностей?

Для разработки структуры я воспользовался подходом Diátaxis. Подход даёт простые и понятные правила структурирования документации, разделяя все статьи на четыре основных категории:

Концепции (Explanations) — описывают работу системы на концептуальном уровне: назначение продукта, описание реализованных бизнес-процессов, etc.
Справочники (References) — технические характеристики системы, например, спецификации API, параметры системы, команды CLI
Туториалы (Tutorials) — обучающие материалы, представленные в виде инструкций для решения конкретных задач
Гайды (How-to Guides) — практические пошаговые руководства по работе с продуктом

Я расчертил лист своего блокнота на четыре столбца и начал раскидывать будущие статьи документации по этим столбцам.

На первой итерации мне хватило двух категорий: концепции (чтобы описать назначение и принципы работы сервиса) и гайды (чтобы описать основные сценарии работы с сервисом).

4. Напишите доку.

Заполните собранный каркас хорошим техническим текстом.

На старте документации у меня получилось всего шесть статей:

* Главная с описанием сервиса
* Две концептуальных статьи с верхнеуровневым описанием процессов, которые реализует сервис
* Три пошаговых инструкции, описывающих пользовательские сценарии

Мало? Ничего страшного — ведь есть последний шаг ↓

5. Дополняйте и развивайте вашу документацию.

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

Бонус-шаг: Организуйте процессы обновления документации.

А вот об этом мы поговорим как-нибудь в следующий раз)

P.S. Расскажите в комментариях, как вы создаёте док.системы с нуля, пользуетесь диатаксисом или какими-нибудь другими методиками? И ставьте птичек, если вам понравился пост🕊