6.07. Практика
Практика
В реальной инженерной деятельности документация функционирует не как статичный набор артефактов, а как динамическая система, встроенная в управленческие, коммуникационные и технические процессы. Её качество определяется не только полнотой и точностью формулировок, но и адекватностью инструментам, ролям и контексту проекта. Ниже рассматриваются ключевые аспекты практической работы с документацией в условиях современных ИТ-проектов.
Договорные отношения с заказчиком как основа документационного контекста
Любая разработка программного обеспечения или информационной системы ведётся в рамках договорных отношений, которые задают юридические, финансовые и временные рамки проекта. Договор и приложения к нему (в первую очередь — техническое задание) формируют юридически значимое поле требований, выход за которое требует формального согласования.
На практике это означает:
- ТЗ становится привязкой к стоимости и срокам: любое требование, не включённое в утверждённое ТЗ, рассматривается как изменение объёма работ и оформляется через допсоглашение;
- Документация становится частью поставки: комплект программной документации (по ЕСПД или внутреннему регламенту) указывается в спецификации поставки и подлежит приёмке наравне с кодом;
- Ответственность за качество фиксируется в договоре: гарантийные обязательства, штрафные санкции за невыполнение требований, условия сдачи-приёмки — всё это влияет на глубину и формальность документирования.
Таким образом, договор определяет не только «что делать», но и «как задокументировать результат».
От технического задания к функциональной спецификации
Техническое задание, особенно в формате ГОСТ, часто формулируется на уровне бизнес-целей и общих требований. Для передачи в разработку требуется декомпозиция — превращение абстрактных требований в конкретные, проверяемые и реализуемые единицы.
Эту функцию выполняет функциональная спецификация — документ, описывающий:
- сценарии взаимодействия пользователя с системой (user journeys);
- бизнес-правила и условия ветвления;
- форматы входных и выходных данных;
- поведение системы в штатных и аварийных ситуациях.
В отличие от ТЗ, спецификация:
- ориентирована на разработчика и тестировщика;
- может быть оформлена в виде Confluence-страницы, спецификации OpenAPI или даже набора пользовательских историй;
- допускает итеративную проработку в процессе уточнения требований.
Важно: функциональная спецификация не заменяет ТЗ, а развёртывает его. При этом между ними должна поддерживаться прослеживаемость — каждая функция в спецификации должна быть связана с пунктом ТЗ.
Постановка задач в системах управления проектами (JIRA и аналоги)
На этапе разработки требования трансформируются в задачи (issues, tickets) в системах управления проектами — чаще всего JIRA, но также Azure DevOps, YouTrack, Redmine и др.
Качественная постановка задачи включает:
- чёткий заголовок, отражающий суть (не «Сделать», а «Реализовать фильтр по дате в реестре входящих»);
- описание в терминах бизнес-ценности («Пользователь должен иметь возможность отобрать документы за последнюю неделю»);
- ссылку на источник требования (ТЗ, спецификация, протокол согласования);
- критерии приёмки (acceptance criteria) — условия, при выполнении которых задача считается завершённой;
- макеты, схемы, примеры данных (в приложениях или через Figma/Whimsical-ссылки);
- метки: компонент, приоритет, оценка трудозатрат.
Такой подход превращает JIRA не в «баг-трекер», а в живой реестр требований, интегрированный с разработкой, тестированием и релизами.
Тест-кейсы как форма верификации требований
Тест-кейс — это процедурное описание проверки конкретного требования или функции. В отличие от методики испытаний (ПМИ), тест-кейсы:
- более детализированы;
- ориентированы на исполнителя (тестировщика);
- могут быть ручными или автоматизированными;
- хранятся в специализированных системах (TestRail, Xray, Zephyr) или прямо в JIRA.
Структура тест-кейса включает:
- Название (отражающее проверяемую функцию);
- Предусловия (состояние системы перед началом);
- Шаги (последовательность действий);
- Ожидаемый результат;
- Постусловия (восстановление состояния, если необходимо).
Хорошая практика — привязка тест-кейса к задаче и к требованию. Это позволяет отслеживать покрытие: если для требования нет тест-кейсов — оно не проверяется.
Протоколы: фиксация результатов взаимодействия
Протокол — это официальный документ, фиксирующий факт и результаты определённого события. В ИТ-проектах выделяют несколько типов:
- Протокол тестирования — результаты выполнения тест-кейсов или ПМИ, с указанием пройденных/проваленных проверок;
- Протокол интеграции — фиксация успешного (или неуспешного) взаимодействия между системами, включая обмен данными, ошибки, согласованные форматы;
- Протокол приёмки — акт, подписываемый заказчиком и исполнителем, подтверждающий соответствие результата ТЗ.
Протоколы обладают юридической силой и используются при разрешении споров, поэтому их оформление должно быть безупречным: дата, участники, конкретные результаты, подписи.
Проектирование и документирование интеграций
Интеграция между информационными системами — одна из наиболее уязвимых и сложных областей. Её документирование требует особой дисциплины.
Документация по интеграции должна включать:
- Цель интеграции (какой бизнес-процесс поддерживается);
- Схему взаимодействия (диаграмма последовательности, BPMN-фрагмент);
- Технические детали:
- endpoint (URL);
- метод HTTP (GET/POST/PUT);
- формат тела запроса/ответа (JSON/XML с примерами);
- заголовки (Content-Type, Authorization);
- схема авторизации (OAuth2, API-key, Basic Auth);
- коды ответов и обработка ошибок;
- Частота и триггеры (по расписанию, по событию, по запросу);
- Механизмы повторных попыток и устойчивости (retry policy, dead-letter queue);
- Требования к безопасности и логированию.
Часто такая документация оформляется в виде OpenAPI-спецификации, дополненной пояснительным текстом. Для внутренних интеграций — в Confluence с живыми диаграммами (Mermaid, Draw.io).
Инструменты изложения и фиксации требований
Выбор инструмента влияет на качество и долговечность документации. На практике используются:
- Confluence / Notion / Wiki — для живой, гипертекстовой документации с версионированием и совместным редактированием;
- Markdown + Git — для технических спецификаций, встраиваемых в репозиторий (docs-as-code);
- Docusaurus / MkDocs / Sphinx — для публикации документации в виде веб-сайта;
- PlantUML / Mermaid / Draw.io — для визуализации архитектуры, потоков данных, сценариев;
- OpenAPI / AsyncAPI — для спецификации API;
- JIRA / Trello / Azure DevOps — для управления требованиями в разрезе задач.
Ключевой принцип: документация должна быть там, где её читают и используют — рядом с кодом, в трекере задач, в среде разработки.
Ревью требований и документов
Ревью — неотъемлемая часть обеспечения качества документации. Оно проводится на всех уровнях:
- Аналитик ↔ бизнес-заказчик — проверка полноты и корректности требований;
- Аналитик ↔ архитектор — оценка реализуемости и архитектурных последствий;
- Аналитик ↔ разработчик — уточнение деталей, выявление неоднозначностей;
- Аналитик ↔ тестировщик — проверка тестируемости и формулировки критериев приёмки.
Формат ревью:
- синхронный (встреча, whiteboard-сессия);
- асинхронный (комментарии в Confluence, GitHub PR, JIRA).
Результат — итеративное улучшение документа до состояния, пригодного для реализации.