Техническая документация в заказной разработке программного обеспечения

Проектная документация в государственных информационных системах входит в состав контракта как одна из обязательных частей исполнения. Перечень документов, подлежащих сдаче, фиксируется в техническом задании. К таким документам относятся частные технические задания, технический проект, программа и методика испытаний, рабочая документация, включая руководства пользователя и администратора. Базовый состав документов определяется стандартами ГОСТ 34 (для АСУ) или ГОСТ 19 (для ПО) в зависимости от требований заказчика. Однако на практике каждый крупный заказчик, особенно федеральные органы власти, использует собственные шаблоны, которые имеют приоритет над ГОСТами. В ходе выполнения контракта помимо типового перечня могут потребоваться дополнительные документы, например проектные решения или спецификации взаимодействия с прикладными подсистемами, которые детально фиксируют архитектурные решения и упрощают последующее сопровождение системы.

Типы технической документации в проектах заказной разработки

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

1. Проектная и отчетная документация создается в рамках контракта и подлежит сдаче заказчику. В типовой состав входят: проектные решения, технический проект, постановка задачи, описание баз данных, руководство программиста, руководство по техническому обслуживанию, технический паспорт. Структура этих документов задается либо стандартами, либо шаблонами конкретного заказчика. В проектах для федеральных органов власти шаблоны ежегодно обновляются. В ходе выполнения контракта могут потребоваться документы, которые прямо не перечислены в техническом задании, например спецификации взаимодействия с прикладными подсистемами, их подготовка также необходима для успешной приемки.
2. Эксплуатационная документация предназначена для пользователей и администраторов системы после ввода в эксплуатацию. Это руководство пользователя, руководство администратора, правила развертывания и настройки. Такие документы пишутся совместно техническими писателями, аналитиками, разработчиками и DevOps-инженерами. DevOps дает инфраструктурные разделы (развертывание, мониторинг, резервное копирование, CI/CD), а аналитик с техническим писателем готовят функциональную часть. Руководство пользователя, как правило, готовится на основе сценариев работы, предоставленных аналитиками, и содержит текстовые инструкции со скриншотами. Перечисленные документы, в отличие от проектных, могут быть менее жестко регламентированы по форме, но их содержание должно точно соответствовать реализованной функциональности.
3. Внутренняя техническая документация, которая не входит в отчетность, необходима для работы команды. К ней относятся архитектурные решения, спецификации интеграций, описание CI/CD-конвейера, внутренняя база знаний. Такая документация ведется в системах управления знаниями и служит источником информации для текущей разработки и онбординга новых сотрудников. Внутренние документы часто имеют более свободную структуру, они фиксируют ключевые проектные решения, которые впоследствии могут быть использованы при актуализации отчетной документации.
4. Отдельную группу составляет документация, регулируемая нормативными актами на уровне ведомств или межгосударственных образований. Например, в проектах, где информационные сервисы участвуют в обменах в рамках интегрированной информационной системы Евразийского экономического союза, требования к документации определяются решениями Евразийской экономической комиссии и обязательны для всех участников такого обмена. Для таких контрактов состав документов, их структура и порядок согласования заданы нормативными документами ЕАЭС. Любые изменения в нормативной базе влекут за собой актуализацию как самих документов, так и реализованных сервисов.

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

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

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

• Системный аналитик отвечает за документы, фиксирующие бизнес-логику и правила взаимодействия: постановку задачи, описание процедур информационного обмена, структуры электронных документов. Аналитик изучает нормативную базу: решения, порядки, регламенты, на основе которых проектируется поведение системы, и переносит эти требования в текстовое описание. В проектах с формализованными моделями данных аналитик также работает с моделями предметной области, описывая элементы данных, их типы и связи. При внесении изменений в существующие документы он рассматривает новые версии нормативных актов или замечания, поступившие от участников процесса, и корректирует описание процедур и структур.
• Архитектор и ведущий разработчик создают проектное решение и спецификации взаимодействия. Эти документы фиксируют, каким образом система будет реализована технически: определяют технологический стек, схему интеграций, распределение функций между сервисами, модель данных на уровне базы данных. В процессе разработки архитектурные решения могут уточняться, и тогда документация обновляется параллельно с изменениями в коде. В проектах, где используются формальные модели, архитектор или ведущий разработчик участвует в описании модели взаимодействия и структуры сообщений, которые впоследствии ложатся в основу технических документов.
• Тестировщик совместно с техническим писателем прорабатывает методики проверок, тестовые сценарии, критерии приемки для программы и методики испытаний. Тестировщик описывает конкретные сценарии проверки, входные данные и ожидаемые результаты, а технический писатель оформляет эти материалы в соответствии с требованиями к отчетной документации. В проектах с нагрузочным тестированием методика разрабатывается с участием ведущего разработчика, который определяет параметры нагрузки и критерии успешности.
• DevOps-инженер участвует в создании руководства администратора, описания технологического процесса развертывания и правил настройки инфраструктуры. Эти документы содержат информацию о конфигурации серверов, сетевых взаимодействиях, процедурах мониторинга и резервного копирования. В проектах с автоматизированным развертыванием в документацию включаются также описание CI/CD-конвейера и перечень используемых инструментов. Руководство администратора часто пишется в соавторстве с техническим писателем, который приводит описания к единому стилю и формату.
• Технический писатель выполняет связующую функцию между специалистами разных профилей. Он собирает материалы, предоставленные аналитиками, архитекторами, разработчиками и тестировщиками, приводит их к единому стилю, проверяет соответствие шаблонам заказчика, согласованность и полноту описания, выявляет противоречия, оформляет итоговые документы. Уровень вовлеченности технического писателя варьируется в зависимости от его компетенций, опыта и технической подготовки. При создании сложной документации, содержащей сотни страниц и множество таблиц, технический писатель координирует работу всех участников, отслеживает версии и обеспечивает целостность конечного пакета.

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

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

Управление версионностью и совместная работа, методология Docs as Code

В текущей практике мы используем Git-репозитории для хранения технической документации, но не применяем методологию Docs as Code в ее классическом понимании. Документация создается в формате Word в соответствии с требованиями заказчика, а в репозитории хранятся готовые файлы в виде бинарных объектов. Такой подход сложился по нескольким причинам.

Основной фактор – жесткие требования заказчиков к формату сдачи. В государственных проектах шаблоны документации утверждаются на уровне контракта и предоставляются именно в формате Word. Структура, стили оформления, состав разделов и даже типографика заданы заранее. Кроме того, многие документы содержат сложные элементы верстки: многостраничные таблицы с множеством колонок, схемы, которые необходимо создавать в специализированном ПО, встроенные изображения с высокими требованиями к разрешению. В некоторых проектах схемы создаются в программах, доступ к которым возможен только через VPN-подключение к контуру заказчика, и выгружаются оттуда в виде изображений, которые затем вставляются в документ. Перенос такой документации в языки разметки, например Markdown, сопряжен с потерей форматирования, а поддержка сложных таблиц и многоколоночных макетов в большинстве инструментов разметки ограничена. Автоматическая конвертация между форматами также не всегда дает приемлемый результат: даже при правильно настроенных стилях могут возникать ошибки, требующие ручной правки.

Еще одна причина – необходимость работать в закрытых контурах заказчика. В ряде проектов заказчик предоставляет собственные шаблоны и требует, чтобы документы велись непосредственно в его системе, без возможности использования внешних инструментов. В таких условиях внедрение Docs as Code потребовало бы дополнительной синхронизации между внутренним репозиторием и системой заказчика, что усложняет процесс и увеличивает риск расхождений. Кроме того, процесс согласования часто включает правки, которые заказчик вносит непосредственно в Word-файл или оставляет комментарии в нем; перенос этих изменений обратно в исходную разметку создает дополнительный ручной труд и не всегда оправдан с точки зрения затрат времени.

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

К числу таких преимуществ относится параллельная работа нескольких авторов над одним документом, полная история изменений с привязкой к задачам и коммитам, возможность ревью через те же инструменты, что используются для кода. При использовании Docs as Code документация хранится в том же репозитории, что и исходный код, что упрощает синхронизацию версий. Автоматическая генерация выходных форматов Word, PDF, HTML позволяет получать документ в нужном виде без ручного форматирования. Кроме того, можно использовать переменные и подстановки для унификации повторяющихся данных, например номеров контрактов или наименований участников, что сокращает рутинные правки при обновлении.

Переход к Docs as Code требует ресурсов. Необходимо настроить инфраструктуру: выбрать язык разметки, определить набор плагинов для поддержки сложных элементов, настроить конвейер генерации и шаблоны оформления. Потребуется участие DevOps-инженеров, а также специалиста по информационной безопасности для разграничения прав доступа. Техническим писателям и другим участникам процесса потребуется обучение работе с новыми инструментами и правилами внесения изменений. Поэтому Docs as Code чаще всего внедряется поэтапно, начиная с пилотных проектов, где документы не имеют жестких требований к формату и процесс их согласования уже достаточно устоялся, что позволит отработать технологию и оценить экономию времени без риска для контрактной отчетности.

Передача экспертизы как следствие культуры документирования

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

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

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

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

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