Навигатор по нормативной документации
ERD и словарь сущностей — Entity Relationship, нормализация, SQL. Карта — о разделе.
Навигатор - карта раздела технического письма
В отечественных ИТ-проектах часто встречаются два параллельных "языка" документации:
- комплект на программное изделие (единая система программной документации, серия 19);
- комплект на автоматизированную систему (серия 34, плюс уточняющие требования к содержанию документов).
Этот навигатор удобно использовать как точку входа — сначала выбрать контур проекта, потом стадию, затем конкретный тип документа и его владельца.
Каталоги стандартов и готовые шаблоны полезны исполнителю, но не заменяют понимание логики — какой документ на какой стадии, кто его пишет и что в нём должно быть по смыслу, а не только по форме. Ниже — практическая карта без привязки к конкретным поставщикам шаблонов.
Два контура — когда что выбирать
| Ситуация | Базовый контур | Типичный "якорный" документ |
|---|---|---|
| Разработка или поставка ПО как изделия (модуль, библиотека, десктопное/серверное приложение, микросервисный продукт) | Серия 19 (ЕСПД) | Техническое задание на программу |
| Создание АС целиком: бизнес-процессы + люди + оборудование + ПО + эксплуатация | Серия 34 | Техническое задание на создание АС |
| Госзаказ, ОПК, энергетика, медицина, ЖКХ — в договоре прямо указан комплект по 34-й серии | Серия 34 (+ программные документы как часть АС) | ТЗ на АС + проектная документация по стадиям |
| Стартап, внутренний продукт, SaaS без формального ГОСТ в договоре | Внутренний регламент (часто "ГОСТ-подобный") | BRD / PRD / backlog + выборочно формальные акты |
Правило для аналитика: если заказчик автоматизирует организацию и процессы, а не только "код в репозитории", почти всегда в игру входит 34-я серия. Если предмет договора — поставка и сопровождение программы, опорой остаётся 19-я серия.
Ошибка, которую видят на приёмке: ТЗ на программу (серия 19) подают вместо ТЗ на АС (серия 34), когда в контракте фигурирует "автоматизированная система" или "АСУ". Документ может быть грамотным, но юридически не тем.
Стадии создания АС и роль аналитика
Стадии создания автоматизированной системы (классическая модель) задают очередность решений, а не "бумаги ради бумаги":
| Стадия | Смысл для проекта | Где чаще всего участвует аналитик |
|---|---|---|
| 1. Обоснование | Нужна ли АС, эффект, риски, альтернативы | Формулировка целей, KPI, границ |
| 2. Техническое задание | Договорённость "что и при каких условиях" | Требования, объекты автоматизации, приёмка |
| 3. Эскизный проект | Выбор варианта архитектуры и состава | Варианты, схемы, оценка трудозатрат |
| 4. Технический проект | Детальные проектные решения до разработки | Разделы по подсистемам, ИО, техсредства, ПО |
| 5. Рабочая документация | Реализация и комплект поставки | Уточнение спецификаций, трассировка к ТЗ |
| 6. Ввод в эксплуатацию | Обучение, опытная эксплуатация, акты | Сценарии приёмки, критерии "система жива" |
На стадиях 1–4 аналитик — соавтор смысла; на 5–6 — хранитель трассируемости (требование из ТЗ → тест в ПМИ → пункт руководства).
Комплект документов технического проекта (для АС)
На стадии технического проекта заказчик ожидает не один файл, а набор взаимосвязанных разделов. Типичная логика (имена в договорах могут отличаться):
| Раздел / документ | Что фиксирует | Чем помогает команде |
|---|---|---|
| Пояснительная записка к ТП | Обоснование выбранных решений, сравнение вариантов | Согласование с заказчиком и экспертизой |
| Схемы (структурные, функциональные, информационные) | Архитектура "на одном взгляде" | Связь с разработкой и интеграцией |
| Описание информационного обеспечения | Данные, справочники, потоки, качество | ERD, словари, миграции |
| Описание программного обеспечения | Состав ПО, версии, зависимости | Спецификация, CI/CD, лицензии |
| Описание технических средств | Серверы, сеть, отказоустойчивость | Инфраструктура и ИБ |
| Описание организационного обеспечения | Роли, регламенты, обучение | Оргизменения при внедрении |
| Описание метрологического / метрологически значимого обеспечения | Измерения, поверка (если применимо) | Отраслевые ниши |
| Ведомость документов ТП | Перечень всего комплекта | Контроль полноты при сдаче |
Практический совет: не смешивайте в одном PDF "всё про всё". Разделение по типам обеспечения снижает дублирование и упрощает приёмку: эксперт по ИБ читает свой блок, эксплуатация — свой.
Подробные разборы отдельных видов документов — в материалах раздела по техническому письму (ТЗ, спецификация, ПМИ, руководства по ролям).
Комплект на программное изделие (ЕСПД)
Для программы как изделия ключевые типы документов (не обязательно все в каждом проекте):
| Тип | Назначение |
|---|---|
| Техническое задание | Требования и приёмка |
| Спецификация | Состав программ и документации в поставке |
| Пояснительная записка | Обоснование и архитектура |
| Описание программы | Логика и структура для сопровождения |
| Программа и методика испытаний | Формальные испытания |
| Руководства (пользователя, оператора, программиста, администратора и др.) | Эксплуатация по ролям |
| Формуляр | Паспорт изделия, версии, комплектация |
| Ведомость эксплуатационных документов | Опись того, что отдаётся заказчику |
Стадии разработки ПО (предпроект, проект, рабочая документация, внедрение) из серии 19 задают когда появляется каждый тип. В гибких командах стадии часто сжимают в спринты, но юридически значимый комплект всё равно должен быть восстановим к релизу.
Обозначения и версии
Единые правила обозначения документов и программ нужны, чтобы:
- не путать "ТЗ v3" с "ТЗ от 2023";
- однозначно ссылаться в спецификации и актах;
- вести лист регистрации изменений, а не править утверждённый PDF "тихо".
Рабочая схема для команды:
- Код системы + тип документа (ТЗ, СП, ПМИ, РП…) + порядковый номер + номер изменения.
- Любая правка после утверждения — новая строка в листе изменений или оформленное дополнение, а не перезапись файла без следа.
- В wiki/Confluence — зеркальная метка "соответствует обозначению X.ТЗ.001-02".
| Артефакт agile / продуктовый | Часто соответствует по смыслу | Как не потерять трассировку |
Мост к современной практике (Agile, API, wiki)
Формальный комплект и "живая" документация не враги, если явно разделить статусы:
| Артефакт agile / продуктовый | Часто соответствует по смыслу | Как не потерять трассировку |
|---|---|---|
| Epic / Feature | Раздел требований ТЗ | ID требования в ТЗ ↔ ID в трекере |
| User Story | Функциональное требование | Матрица "история — пункт ТЗ — тест" |
| OpenAPI / Swagger | Описание программных интерфейсов | Версия API в спецификации поставки |
| ADR | Фрагмент пояснительной записки / ТП | Номер ADR в ПЗ или в приложении к ТП |
| Test plan в Jira | ПМИ (внутренняя часть) | Экспорт сценариев в формальную ПМИ к релизу |
| Runbook / playbook | Руководство оператора / администратора | Сверка ролей и процедур |
| README в репозитории | Не заменяет РП для госзаказа | Ссылка из РП: "исходники и сборка — см. репозиторий тега v…" |
Принцип: wiki ускоряет работу; утверждённый комплект фиксирует обязательства. Аналитик следит, чтобы критичные решения из обсуждений не оставались только в чате.
Испытания — два уровня
| Уровень | О чём | Кто опирается |
|---|---|---|
| Испытания программы | Модули, регресс, модульные/интеграционные | Разработка, QA |
| Испытания АС | Комплексные, приёмо-сдаточные, опытная эксплуатация | Заказчик, комиссия |
Виды испытаний АС (предварительные, опытные, приёмочные и др.) задают разные протоколы и акты. ПМИ должна покрывать пункты ТЗ, иначе приёмка превращается в "покажите демо".
Чек-лист перед сдачей комплекта
- В договоре назван правильный контур: программа или АС.
- ТЗ согласовано до начала ТП (или зафиксировано дополнение с подписью).
- Спецификация перечисляет все программы и документы в поставке, включая сторонние и заимствованные.
- Руководства не дублируют друг друга: у каждой роли свой документ.
- ПМИ ссылается на конкретные пункты требований, а не на "система должна работать хорошо".
- Обозначения и лист изменений согласованы между PDF, печатью и электронной копией.
- Внутренняя wiki помечена: что является черновиком, что — экземпляром для приёмки.
Что сознательно не переносить из "каталогов и шаблонов"
Сторонние сборники стандартов и примеры документов полезны как ориентир формы, но в учебную и проектную базу знаний не стоит тащить:
- готовые таблицы и тексты "под копипаст" — они устаревают и привязаны к чужим вымышленным системам;
- перечни PDF без методики — их заменяет этот навигатор плюс разборы по каждому виду документа;
- смешение ЕСКД и ЕСПД без пояснения контекста — в IT-проекте нужно явно указать, какой контур главный.
Собственная ценность энциклопедии — связка смысла, ролей и стадий, а не дублирование официальных текстов стандартов.
Куда идти дальше в энциклопедии
- Техническое задание по ГОСТ — программное изделие.
- Спецификация по ГОСТ — состав поставки.
- Дополнительные виды проектной документации — ТЗ на АС, ПМИ, изменения.
- Документация аналитика — артефакты вне формального ГОСТ.
Дополнение — быстрый алгоритм выбора комплекта документов
- Определите объект договора: программа или автоматизированная система.
- Зафиксируйте стадии: только разработка ПО или полный цикл внедрения.
- Согласуйте обязательные артефакты и критерии приемки до старта работ.
- Свяжите каждый артефакт с ответственным и сроком обновления.
Матрица ответственности
| Документ | Кто владелец | Кто согласует | Когда обновлять |
|---|---|---|---|
| ТЗ | аналитик | заказчик, архитектор | при изменении требований |
| ПМИ | QA-лид | заказчик, техлид | перед приемкой релиза |
| Руководства | техписатель | эксплуатация, поддержка | при изменении процессов |