Разработка технической документации

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

Для госзаказчиков и корпоративных клиентов техническая документация — условие приёмки. Без неё акт не подписывают, независимо от качества самой системы.

Разработка технической документации на старте, а не в конце — правило, которое экономит деньги. Писать доку параллельно с разработкой дешевле, чем восстанавливать её по факту запуска.

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

Разработка технической документации начинается с инвентаризации: что уже есть, что нужно создать, какой стандарт применяется. Для государственных систем — ГОСТ 34. Для программных изделий — ГОСТ 19. Для систем с требованиями к информационной безопасности — добавляются профили защиты.

Рабочая документация ГОСТ 34 включает несколько десятков возможных документов. Не все нужны для каждого проекта. Мы согласовываем состав документации с заказчиком и проектируем минимально необходимый комплект, который закроет требования приёмки.

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

API-документация — отдельное направление. Здесь стандарт — OpenAPI (Swagger). Описываем эндпоинты, параметры, форматы данных, коды ответов и примеры запросов. Документация генерируется автоматически из кода или пишется вручную — зависит от стека и требований к детализации.

По итогам работы заказчик получает комплект документов в согласованном формате — Word, PDF или интерактивная документация в Confluence. Для государственных контрактов — с подписями и штампами в соответствии с регламентом.