Что и как должно быть в документации
Чтобы документация была полезной, нужно ответить на три главных вопроса:
- для кого она написана,
- зачем им это читать и
- у кого есть нужное знание.
Давайте разберем это подробнее с помощью фреймворка APC: Audience — Аудитория, Purpose — Цель, Collaboration — Сотрудничество.
Аудитория: кто будет это читать?
Первое, что нужно понять – это кто будет читать вашу документацию. От этого зависит, каким будет язык и стиль изложения, насколько подробно нужно описывать детали и какие термины использовать. Вот основные категории читателей:
- Конечные пользователи: Не всегда разбираются в технических деталях. Документация для них должна быть простой и понятной.
- Разработчики: Нуждаются в технически точной информации, примерах кода и описаниях API.
Цель: зачем ему это читать?
После определения аудитории, важно понять, зачем им нужна эта документация. Для этого можно использовать JTBD, но чаще всего достаточно одной из этих категорий:
- Обучение: Помочь новым пользователям освоить продукт.
- Решение проблем: Предоставить инструкции по устранению неполадок.
- Интеграция и разработка: Помочь разработчикам интегрировать продукт с другими системами.
- Администрирование: Обеспечить системных администраторов нужной информацией для поддержания работоспособности продукта.
Сотрудничество: кто хранит знание?
На позиции техписа у вас, скорее всего, нет полного понимания продукта или системы, поэтому в одиночку писать документацию очень и очень сложно. Чтобы всё-таки ваши статьи не были поверхностными, высосанными из пальца, да и просто — правдивыми, надо находить держателей знания и проводить с ними интервью.
Хранителем знания может быть продакт, разработчик, тестировщик, пользователь — важно зафиксировать это в задаче или статье и держать контакт со всеми заинтересованными. Ведь у них тоже может быть только кусочек знания, а работа с техписом поможет получить полную картину и избежать ошибок.
Итого: любой текст, будь то статья, пост в блоге или техническая документация, должен начинаться с ответов на три вопроса:
- Кто будет это читать?
- Зачем ему это читать?
- Где ещё есть эта информация?
Запомните фреймворк APC — Audience, Purpose, Collaboration — и больше не выпускайте тексты, которые ему не соответствуют.