В статье рассматривается что, зачем и как документировать в заказной и коммерческой разработке, чтобы спасти проект и нервы.
Разработчики видят в документации бюрократию, отвлекающую от настоящей работы. Заказчики и менеджеры — единственную гарантию, что получат то, что просили. Истина, как всегда, посередине. В условиях договорных обязательств (особенно с госзаказчиком) документация — это не бумажка, а юридически значимый артефакт, такой же важный, как и сам код.
Давайте разберемся, как сделать ее союзником, а не врагом.
Часть 1. Два мира, два подхода - госзаказ или внутренний заказ
1.1. Заказная разработка для госзаказчика (по 44-ФЗ, 223-ФЗ)
Жесткие стандарты (ГОСТы, отраслевые требования). Докум��нтация - первична. Часто оплачивается отдельно, ее объем и формальность прописаны в контракте.
Требуется гарантия соблюдения процедур, проверяемость, прозрачность расходов бюджета. Документы - основа для приемки и защиты от претензий Счетной палаты.
Фокус на верификации и валидации: «Мы построили именно то, что описано в ТЗ, и это работает так, как написано в руководстве».
1.2. Коммерческая (внутренняя) разработка
Agile-принципы, итеративность и скорость. Документация эволюционирует вместе с продуктом.
Здесь Техническое задание в классическом понимании (единый монолит) - большая редкость. Вместо него используется живой бэклог продукта.
Работа ведётся так:
1. Формируется общее видение (Vision). Документ на 1-2 страницы с целями, целевой аудиторией и ключевыми ценностями продукта.
2. Создаются эпики и пользовательские истории (User Stories). Это и есть те самые фрагменты ТЗ. Описывается конкретная функциональность с точки зрения пользователя: «Как [роль], я хочу [цель], чтобы [выгода]».
3. Уточнение перед разработкой. Непосредственно в начале спринта или перед взятием задачи в работу история детализируется. Документируется именно этот фрагмент: добавляются критерии приемки (Acceptance Criteria — AC), набрасываются макеты интерфейса (wireframes), описываются бизнес-правила. Этот уточнённый «пакет» и отдаётся в разработку.
4. Документирование «на ходу». Архитектурные решения (ADR — Architecture Decision Record), контракты API (OpenAPI) и ключевые конфигурации создаются параллельно с кодом.
Требуется быстрая доставка ценности, получение обратной связи и адаптация к изменениям рынка.
Фокус на рабочем продукте, а не на полном комплекте документов. Документация служит для передачи контекста внутри команды и фиксации решений.
В первом случае документация - щит и меч исполнителя при сдаче проекта. Во втором - карта и компас для движения по быстрому течению.
1.2.1. Риски фрагментарного подхода и как их mitigate
К чему приводят упрощения, когда «пишут фрагмент ТЗ и тут же отдают в разработку без системного подхода:
Системная несогласованность. Отдельные фичи, написанные разными людьми/командами в разное время, начинают конфликтовать между собой. Получается лоскутное одеяло вместо целостного продукта.
Технический долг в документации. Накопленные фрагменты теряют актуальность, не сводятся в общую картину. Новый разработчик не может понять систему в целом.
Утрата видения. Команда тонет в деталях текущих спринтов и забывает общую цель (Vision). Разработка превращается в набор хаотичных улучшений.
Проблемы с онбордингом. Невозможно передать проект другой команде или масштабироваться.
Как этого избежать, сохранив гибкость:
Храните фрагменты системно. Используйте Issue Tracker (Jira, Linear) как единый источник правды, связывая задачи с ветками кода и пул-реквестами.
Поддерживайте живые карты. Регулярно обновляйте высокоуровневую диаграмму архитектуры (C4 Context & Container level) и глоссарий терминов.
Пишите ADR. Это дешевый и эффективный способ зафиксировать почему система устроена так, а не иначе.
Проводите регулярные ретроспективы по документации. Включите в ретроспективу спринта вопрос: «Достаточно ли мы документируем решения, чтобы через 3 месяца их можно было понять?».
Часть 2. Базовый минимум - какие документы нельзя игнорировать
Фазы проекта | Выходные документы | Примечание |
Фаза проектирования и согласования | Техническое задание (ТЗ) / ЧТЗ | Король документов. Без него все остальное бессмысленно. Должно содержать нефункциональные требования (NFR): нагрузка, безопасность, отказоустойчивость. |
Технический проект (ТП) / Общее описание си��темы | Часто пренебрегается. Должен отвечать на вопрос «КАК» мы будем делать то, что в ТЗ. Описание архитектуры (диаграммы компонентов, взаимодействия), выбор технологий, схемы баз данных. Это страховка от архитектурных просчетов. | |
Фаза разработки и внедрения | Протоколы информационного взаимодействия (API Specification) | Описание интеграций. Must have для современных систем. Форматы: OpenAPI (Swagger), AsyncAPI. Это договор между командами, который позволяет работать параллельно. |
Руководство администратора | Инструкция по развертыванию, обновлению, резервному копированию, мониторингу и устранению неисправностей. Критично для эксплуатации. | |
Фаза сдачи и эксплуатации | Руководство пользователя (РП) | Часто делается для галочки. Хорошее РП снижает нагрузку на поддержку. Сегодня это часто не PDF, а интерактивная help-система или скринкасты. |
Акты испытаний (Тест-план / Протоколы тестирования) | Доказательство, что система соответствует ТЗ. Особенно важно для госзаказа. Включает сценарии приемо-сдаточных испытаний. | |
Паспорт системы / Пояснительная записка | Краткий обзорный документ: что это, зачем, из чего состоит, как запустить. Нужен новым сотрудникам или аудиторам. | |
Регламенты (procedures) | На случай инцидентов, масштабирования, миграции данных. | |
Документация на тестовые среды и данные. |
| |
Схемы и описания процессов (BPMN, UML) | Для сложных бизнес-процессов.
|
Часть 3. Инструментарий - от Markdown до Enterprise-решений
Инструмент | Примечание |
Легковесные и гибкие (для коммерческой разработки) | |
Markdown + Git (GitLab, GitHub, Bitbucket) | Документация как код. Версионность, code review, CI/CD для сборки. Идеально для API-документации, репозиториев знаний. |
Confluence, Notion | Классика для вики-систем. Хороши для совместной работы, но могут превратиться в свалку. |
Miro, Draw.io / Diagrams.net | Для схем и архитектуры. |
Классические и формальные (часто для госзаказа) | |
Текстовый документ (МойОфис, Р7-Офис, LibreOffice) + Облачное хранилище | Для обмена ТЗ и утверждения. |
Enterprise-решения IBM DOORS, Enterprise Architect | Для проектов с жестким контролем требований. |
Выбирайте инструменты, которые минимизируют двойную работу. Генерируйте API-доку из кода (Swagger), диаграммы храните в текстовом виде (PlantUML, Mermaid), чтобы они менялись вместе с кодом.
Часть 4. К чему приводят упрощения - коротко о последствиях
Сторона договора | Последствия |
Исполнитель (разработчик) | Технический долг, bus factor (зависимость от 1-2 человек), невозможность масштабировать команду, срывы сроков, финансовые санкции по договору, репутационные риски. |
Заказчик (бизнес) | Привязка к конкретному исполнителю (вендор-лок), высокие затраты на поддержку и развитие, невозможность быстро адаптировать систему под меняющийся рынок, операционные ошибки из-за непонимания логики работы. |
Дружба возможна. Документация и код - не враги, а две стороны одной медали под названием успешный, поддерживаемый и отвечающий целям продукт.
Ключ - в разумном балансе:
Документируйте не все подряд, а то, что ценно и будет использоваться (архитектурные решения, контракты интеграций, процедуры развертывания).
Обновляйте документацию в рамках тех же процессов (например, merge/pull request), что и код.
Хорошая документация снижает риски, ускоряет onboarding и повышает стоимость вашей компании как актива (ведь ее не покинет вся экспертиза).
В условиях договора сильная документация — это не бюрократия, а ваша профессиональная страховка и конкурентное преимущество.
