Документирование программных продуктов
Основная задача технического писателя – создавать понятную и структурированную документацию к программным продуктам. Это трудоемкий процесс, поэтому, чтобы облегчить себе жизнь, действую по алгоритму (см. Схему 1).
Процесс разработки
Схема 1. Процесс документирования ПО
Применяю общепринятый подход к документированию. Действую поэтапно:
- Анализирую задачу. Уточняю детали, декомпозирую задачу, оцениваю примерные сроки. Важно понимать:
- Что документирую. Какой программный продукт.
- Кто целевая аудитория продукта.
- Какие доступны источники информации: тестовый стенд, легаси документов, база знаний, комментарии в коде, специалисты.
- С какой целью создается документация. Кто, где и в каких обстоятельствах будет ей пользоваться.
- Какие документы требуется разработать (исчерпывающий перечень). В какой срок.
- Каким требованиям должны соответствовать документы (стайлгайдам, редакционной политике, нормативам).
- По каким критериям будет оцениваться результат.
- Собираю сведения о продукте. Создаю файловую структуру. Заполняю мастер-документ.
- Составляю документы. Подготавливаю схемы и иллюстрации. Пишу текст. Оформляю внешний вид и нужный формат. Проверяю результат.
- Отправляю документы на проверку (docs review). Устраняю замечания. Вношу исправления и дополнения.
- Закрываю задачу. Удаляю все лишнее. Заполняю Readme-файл. Архивирую.
Этап 1. Анализ задачи
Перед тем, как браться за составление документов, я анализирую задачу и уточняю детали у ее постановщика.
Схема 2. Процесс анализа задачи
В процессе анализа формирую общее представление о продукте, его пользователях, требованиях к результату и о своих предстоящих действиях. Декомпозирую задачу и рассчитываю примерные сроки. Полученную информацию и свои соображения конспектирую в таск-трекере.
На данном этапе технические характеристики и особенности продукта не особо важны. Самое главное – это сформировать общее понимание о нем, целевой аудитории и ожидаемом результате. Остальное смогу выяснить в процессе сбора сведений и составления документов.
Вот мой список вопросов для самопроверки (ответы под катом):
Что документирую? (Какой программный продукт)
- Сервис искусственного интеллекта (ИИ-сервис)
- ИИ-сервис интерпретирует изображения магнитно-резонансной томографии (МРТ) органов малого таза с внутривенным контрастированием для выявления признаков рака предстательной железы.
- Область медицины: лучевая диагностика.
- Код по МКБ-10: С61 Злокачественное новообразование предстательной железы.
- Принцип работы:
- ИИ-сервис встраивается в медицинскую (рентгенологическую) информационную систему.
- Врач-ренгенолог проводит инструментальное обследование пациента. В результате в медицинском архиве изображений (PACS) сохранются снимки (формат DICOM).
- ИИ-сервис автоматически анализирует эти снимки на предмет наличия патологии. Если патология обнаружена, ИИ выделяет “зону внимания” контурной обводкой и внутриконтурной заливкой. Формирует предварительный протокол медицинского исследования.
- Врач-рентгенолог на своем автоматизированном рабочем месте (АРМ) отсматривает снимки и дозаполняет протокол исследования.
Кто и в каких обсоятельствах пользуется продуктом? (Целевая аудитория продукта)
- Врач-рентгенолог при проведении инструментального обследования пациента.
Где взять информацию о продукте и его целевой аудитории? (Источники)
- Тестовый стенд программы – [ссылка]
- Легаси документов – [ссылка на облачное хранилище]
- Корпоративная база знаний - [ссылка]
- Комментарии в коде – [ссылка на репозиторий]
- Сотрудники:
- Фамилия Имя, тимлид разработчиков, telegram: [ссылка], +7(xxx)xxx-xx-xx
- Фамилия Имя, middle-разработчик, telegram: [ссылка], +7(xxx)xxx-xx-xx
- Фамилия Имя, специалист техподдержки, telegram: [ссылка], +7(xxx)xxx-xx-xx
С какой целью создаю документацию? Где и как она будет использоваться?
- Для регистрации программы в Минцифры (реестр отечественного ПО)
- Единый реестр российских программ для ЭВМ и БД. Официальный сайт реестра
Кто будет пользоваться документацией? (Целевая аудитория документов)
- Эксперты Минцифры при оценке программы на ее пригодность для регистрации
- Их заключение влияет на результат: регистировать или нет
Какие документы я должен разработать? (Исчерпывающий перечень)
- Заявление
- Образец лицензионного договора
- Описание процессов жизненного цикла
- Описание функциональных характеристик ПО
- Руководство по эксплуатации ПО
- Технические условия
Какие требования предъявляются к документам? (Корпоративные, нормативные и пр.)
- Методические рекомендации по подаче заявлений и уведомлений. Документ pdf
- Правила формирования и ведения единого реестра программ для ЭВМ и БД. СПС Гарант
- Требования к правообладателям и программам. Официальный сайт Госуслуг
- Применять ГОСТы можно, но не обязательно.
- Заявление в Минцифры заполняется на портале Госуслуг, подписывается усиленной ЭЦП
- Классификатор программ для ЭВМ и БД
Когда пазл сложился в цельную картину, я приступаю к детализации. Погружаюсь в технические характеристики и особенности продукта.
Этап 2. Сбор сведений
Перехожу к обработке источников, начинаю щупать продукт руками, изучать легаси документов и комментарии в коде, общаться со специалистами. В процессе создаю мастер-документ. Это один или несколько файлов, в которых я описываю продукт. Этими описаниями я воспользуюсь на следующем этапе при составлении отдельных документов.
Схема 3. Процесс сбора сведений
На схеме изображен порядок моих действий. Прежде всего я создаю файловую структуру, в которой собираюсь работать, и мастер-документ.
Шаг 1. Файловая структура
Эту структуру я применяю, когда работаю в Google Workspace. Если же необходимо действовать по концепции Docs-As-Code, то структура меняется в зависимости от требований заказчика. Например, некоторые папки размещаются в Github-репозитории и объектном хранилище S3.
- Заявление_в_Минцифры.docx
- Образец_лицензионного_договора.docx
- Описание_процессов_жизненного_цикла.docx
- Описание_функциональных_характеристик.docx
- Руководство_по_эксплуатации.docx
- Технические_условия.docx
- img-001.jpg
- img-002.jpg
- img-003.png
- img-124.png
- diagram-life-cycle-model-001.jpg
- diagram-data-depersonalization-process-001.jpg
- pic-gui-001.png
- pic-gui-002.png
- Глоссарий.docx
- Мастер-документ.docx
- Статья_о_моделях_жизненного_цикла.pdf
- ПНСТ_Системы_ИИ_в_клинической_медицине_Часть_10.pdf
- Readme.docx
Для верхнеуровневой файловой структуры применяю концепцию P.A.R.A. Кликните на папку “Проекты” и сами увидите. Папки и файлы именую по-русски (мне так привычнее), за исключением тех файлов, на которые будут ссылки.
В папку “Документация” я копирую шаблоны документов из папки “Ресурсы”. Если какого-то шаблона у меня нет, то создаю пустой файл.
В папку “Иллюстрации” складываю файлы с рисунками, схемами, чертежами и прочими изображениями, которые планирую вставлять в документы. Файлы именую на латинице.
В папке “Мастер-документ” создаю одноименный файл “Мастер-документ.docx”, в котором я буду описывать продукт на данном этапе. “Глоссарий” предназначен для терминов и определений, чтобы соблюдать единую терминологию.
В папке “Trash” собираю вспомогательные материалы и всякий мусор.
Файл “Readme.docx” содержит описание проекта, а также ответы на мои вопросы, которые я выяснил на предыдущем этапе. По сути, он дублирует описание задачи из таск-трекера. Отличается тем, что содержит мои рабочие заметки.
Шаг 2. Мастер-документ
Мастер-документ служит для меня единым источником (по аналогии с концепцией Single Source Publishing), из которого я буду переиспользовать куски текста при составлении отдельных документов. В идеале этот файл должен содержать все разделы будущих документов.
По мере сбора сведений мастер-документ становится большой “портянкой”. Когда он переваливает за 100 страниц, я его разбиваю на несколько файлов. Именую по разделам. В основном файле оставляю только оглавление с активными ссылками на дочерние файлы.
Шаг 3. Сведения о продукте
Перехожу к непосредственному изучению продукта:
- Пробую продукт на тестовом стенде.
- Вычитываю легаси документов и материалы внутренней базы знаний.
- Заглядываю в программный код и комментарии к нему.
- Общаюсь со специалистами.
Я обратил внимание, что разработчики сильно раздражаются, когда их отвлекают глупыми или неожиданными вопросами. Они живые люди. Им тоже требуется время, чтобы переключиться из режима кодинга в режим общения. Поэтому, когда мне открывают “доступ к телу”, я стараюсь действовать на упреждение.
Во-первых, к моменту общения у меня уже сформировалось представление о продукте, его свойстах и функциях. Во-вторых, я заранее составляю список вопросов и отправляю его своему оппоненту. Вот пример моего сообщения:
Николай, привет!
Сергей поставил мне задачу написать руководство пользователя к ИИ-сервису.
Этот документ нужен для регистрации программы в реестре Минцифры.
Есть вопросы. Нужно 30 мин твоего времени. Голосом в Discord.
Сегодня сможем? Во сколько?
Вопросы:
1. ...
2. ...
3. ...По мере получения информации заполняю Мастер-документ. Это цикличный процесс. Когда по моему профессиональному убеждению информации достаточно для составления отдельных документов, перехожу к следующему этапу.
Этап 4. Составление документов
На этом этапе я заполняю отдельные документы, проверяю и редактирую написанное. Источником информации мне служит мастер-документ. Если у меня возникают дополнительные вопросы, то пользуюсь доступными мне источниками. В том числе продолжаю общаться со специалистами.
Этап 5. Проверка документов (Docs review)
Созданные документы отправляю на проверку. Если в ответ получаю замечания, то оперативно их устраняю и вновь отправляю документ на проверку. Цикл прерывается за отсутствием замечаний.
Этап 6. Завершение задачи
На этом этапе я прикрепляю созданные документы в таск-трекер, удаляю из файловой структуры все лишнее (обычно это папки “Trash” и “Мастер-документ”), переношу в архив папку “Иллюстрации” и дописываю Readme. В идеале у меня должно остаться только самое необходимое:
- diagram-life-cycle-model-001.jpg
- diagram-data-depersonalization-process-001.jpg
- pic-gui-001.png
- pic-gui-002.png
- Заявление_в_Минцифры.docx
- Образец_лицензионного_договора.docx
- Описание_процессов_жизненного_цикла.docx
- Описание_функциональных_характеристик.docx
- Руководство_по_эксплуатации.docx
- Технические_условия.docx
- Readme.docx
Заключение
Создание качественной технической документации - это комплексный процесс, требующий внимания к деталям и постоянного совершенствования навыков. Важно помнить, что хорошая документация помогает не только пользователям, но и всей команде разработки, упрощая процесс разработки и поддержки продукта.
Надеюсь, мой опыт поможет вам в создании эффективной технической документации. Но не забывайте, что каждый проект уникален, и подход к документированию может и должен адаптироваться под конкретные обстоятельства.