Как я создаю техническую документацию

Моя основная задача, как технического писателя, – создавать понятную и структурированную документацию к программным продуктам. Это трудоемкий процесс, поэтому, чтобы облегчить себе жизнь, действую по алгоритму (см. Схему 1).

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

Схема 1. Процесс документирования ПО

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

Этап 1. Анализ задачи

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

Примерно так же себя чувствую, когда приступаю к документированию нового продукта. Изначально я ничего не знаю ни о нем самом, ни о его пользователях, ни о требованиях к результату. Поэтому перед тем, как браться за составление документов, анализирую задачу и уточняю детали у ее постановщика.

Схема 2. Процесс анализа задачи

В процессе анализа формирую общее представление о предстоящих действиях: декомпозирую задачу и рассчитываю примерные сроки. Полученную информацию и свои соображения кратко конспектирую в таск-трекере. План-график прикрепляю отдельным файлом.

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

Вот мой чек-лист для этого этапа:

Когда пазл сложился в цельную картину, я приступаю к детализации. Погружаюсь в технические характеристики и особенности продукта.

Этап 2. Сбор сведений

На предыдущем этапе я выяснил, какими источниками информации могу воспользоваться. Вот они:

• тестовый стенд программы;
• легаси документов;
• корпоративная база знаний;
• программный код и комментарии в коде;
• сотрудники компании.

Перехожу к обработке источников, начинаю общаться со специалистами. В процессе формирую мастер-документ. Это один или несколько файлов, в которых я описываю продукт. Этими описаниями я буду пользоваться на следующем этапе при составлении отдельных документов.

Схема 3. Процесс сбора сведений

На схеме я отразил процесс обработки источников информации и процесс обработки файлов как два параллельных процесса. Думаю, так будет проще для понимания.

Шаг 1. Файловая структура

Прежде всего я создаю файловую структуру, с которой собираюсь работать. Вот вариант моего облачного хранилища на Гугл Диске.

Схема 4. Пример файловой структуры

• Проекты
  • Регистрация в реестре отечественного ПО Минцифры
    • Документация
      • Заявление_в_Минцифры.docx
      • Образец_лицензионного_договора.docx
      • Описание_процессов_жизненного_цикла.docx
      • Описание_функциональных_характеристик.docx
      • Руководство_по_эксплуатации.docx
      • Технические_условия.docx
    • Иллюстрации
      • Исходники
        • img-001.jpg
        • img-002.jpg
        • img-003.png
        • img-124.png
      • Обработано
        • Рисунок_графического_интерфейса_001.png
        • Рисунок_графического_интерфейса_002.png
        • Схема_модели_жизненного_цикла.jpg
        • Схема_процесса_деперсонализации_данных.jpg
    • Мастер-документ
      • Глоссарий.docx
      • Мастер-документ.docx
    • Trash
      • Статья_о_моделях_жизненного_цикла.pdf
      • ПНСТ_Системы_ИИ_в_клинической_медицине_Часть_10.pdf
    • Readme.docx

В папке “Документация” я создаю пустые файлы документов, которые мне нужно составить, или шаблоны таких файлов. Если в моем архиве есть шаблоны таких документов.

В папку “Иллюстрации” складываю файлы с рисунками, схемами и прочими изображениями, которые планирую вставлять в документы.

В папке “Мастер-документ” находится одноименный файл “Мастер-документ.docx”. Именно в этот файл я собираю все сведения о продукте. “Глоссарий” предназначен для терминов и определений, чтобы соблюдать единообразие понятий, используемых в тексте.

В папке “Trash” собираю вспомогательные материалы и всякий мусор.

Файл “Readme.docx” содержит описание проекта и целевой аудитории, а также ответы на мои вопросы, которые я выяснил на предыдущем этапе. По сути, в Readme.docx дублирую описание задачи из таск-трекера.

Обратите внимание, что папки “Иллюстрации”, “Мастер-документ” и “Trash” – временные. После выполнения задачи я их удаляю. В итоге в архиве останeтся только “Документация” с реальными документами и “Readme.docx” с описанием задачи. Вот так:

• Проекты
  • Регистрация ИИ-сервиса в реестре отечественного ПО Минцифры
    • Документация
      • Заявление_в_Минцифры.docx
      • Образец_лицензионного_договора.docx
      • Описание_процессов_жизненного_цикла.docx
      • Описание_функциональных_характеристик.docx
      • Руководство_по_эксплуатации.docx
      • Технические_условия.docx
    • Readme.docx

Шаг 2. Мастер-документ

В результате он становится большой “портянкой”, из которой я переиспользую куски текста при составлении отдельных документов. Когда “Мастер-документ” переваливает за 100 страниц, я его разбиваю на несколько файлов. В основном файле оставляю только оглавление с активными ссылками на дочерние файлы.

Шаг 3. Целевая аудитория

Как правило, вся документация пишется для трех целевых групп:

1. обычные пользователи определенного уровня подготовки;
2. разработчики, тестировщики и иные специалисты, которые поддерживают и дорабатывают продукт;
3. эксперты регулирующих органов власти, грантодатели, участники системы госзакупок.

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

• для обычных пользователей она будет подробной и наглядной, написанной простым языком;
• для технических специалистов – краткой, использующей профессиональную терминологию и сложные примеры кода;
• для экспертов – дополненной юридическими формальностями.

Раньше я писал документ “для всех” без учета целевой аудитории, и получалось, что “ни для кого”. Теперь я создаю портреты пользователей. Например:

Ольга, 38 лет, менеджер по продажам:
- Использует программу раз в месяц.
- Боится что-то сломать.
- Ищет кнопку "Сделать все правильно".

Олег, 27 лет, системный администратор
- Опыт работы: 5 лет в IT-сфере
- Технические навыки: middle+
- Потребности:
	- Не любит "воды" в документации
	- Интересуется новыми технологиями
	- Пользуется программой для рабочих задач

Когда я работаю над документом эти портреты находятся у меня перед глазами. Они помогают не сбиваться со стиля повествования. Сами понимаете, что для Ольги и Олега требуется разные документы как по содержанию, так и по манере изложения.

Шаг 4. Сведения о продукте

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

1. Пробуй сломать продукт.
   Как правило, мне дают доступ к тестовому стенду, где я могу пощупать продукт руками, не опасаясь его сломать. Вся прелесть в том, что даже если мне это удастся сделать, то ругать точно не будут. В худшем случае скажут спасибо, а в лучшем уделят больше времени и внимания моим вопросам.

2. Доберись до легаси документов и комментариев в коде.
   В контексте документации к “легаси” (англ. legacy, наследие) относятся устаревшие документы и наработки, которые утратили свою актуальность. Из них можно почерпнуть общую концепцию продукта, подходы к его разработке и другие полезности. А комментарии разработчиков помогают найти куски кода для иллюстрации будущего текста.

3. Задавай вопросы заранее единым списком.
   Разработчики сильно раздражаются, когда их отвлекают глупыми или неожиданными вопросами. Они живые люди, и им требуется время, чтобы переключиться из режима кодинга в режим общения. Поэтому, когда мне открывают “доступ к телу”, я стараюсь действовать аккуратно.

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

Николай, привет! 
  
Сергей поставил мне задачу написать руководство пользователя к ИИ-сервису. 
Этот документ нужен для регистрации программы в реестре Минцифры.
  
Есть вопросы. Нужно 30 мин твоего времени. Голосом в Discord.
  
Сегодня сможем? Во сколько?
  
Вопросы:
1. ...
2. ...
3. ...

Этап 4. Составление документов

На этом этапе я приступаю к непосредственному написанию документации.

Этап 5. Проверка документов (Docs review)

Этап 6. Завершение задачи

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

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