Что и как должно быть в документации – Ringova
Что и как должно быть в документации

Что и как должно быть в документации

Чтобы документация была полезной, нужно ответить на три главных вопроса:

  • для кого она написана,
  • зачем им это читать и
  • у кого есть нужное знание.

Давайте разберем это подробнее с помощью фреймворка APC: Audience — Аудитория, Purpose — Цель, Collaboration — Сотрудничество.

Аудитория: кто будет это читать?

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

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

Цель: зачем ему это читать?

После определения аудитории, важно понять, зачем им нужна эта документация. Для этого можно использовать JTBD, но чаще всего достаточно одной из этих категорий:

  1. Обучение: Помочь новым пользователям освоить продукт.
  2. Решение проблем: Предоставить инструкции по устранению неполадок.
  3. Интеграция и разработка: Помочь разработчикам интегрировать продукт с другими системами.
  4. Администрирование: Обеспечить системных администраторов нужной информацией для поддержания работоспособности продукта.

Сотрудничество: кто хранит знание?

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

Хранителем знания может быть продакт, разработчик, тестировщик, пользователь — важно зафиксировать это в задаче или статье и держать контакт со всеми заинтересованными. Ведь у них тоже может быть только кусочек знания, а работа с техписом поможет получить полную картину и избежать ошибок.

Итого: любой текст, будь то статья, пост в блоге или техническая документация, должен начинаться с ответов на три вопроса:

  1. Кто будет это читать?
  2. Зачем ему это читать?
  3. Где ещё есть эта информация?

Запомните фреймворк APC — Audience, Purpose, Collaboration — и больше не выпускайте тексты, которые ему не соответствуют.