Модуль 0.2. Инструментарий и среда работы системного аналитика
Ваша ценность как системного аналитика (SA) быстро возрастает, когда артефакты понятны, трассируемы и живут в системе, а не в случайных файлах. В этом модуле зафиксируем правила среды, настроим цепочку инструментов (Confluence/Notion → Jira/YouTrack → Miro/FigJam → репозиторий), введём версионирование документации и раздадим шаблоны (Vision, BRD, SRS, Decision Record). На выходе — рабочая «скелетная» среда, которой можно пользоваться в проекте на следующий день.
Базовые принципы среды (как сотруднику — к исполнению)
-
Единый источник правды (SSOT).
– Wiki (Confluence/Notion) — «читабельная витрина» для бизнеса и команды.
– Репозиторий (Git) — каноническая версия артефактов, которые влияют на разработку/тесты (OpenAPI, схемы событий, JSON-Schema, PlantUML/Mermaid, BDD-файлы, чек-листы).
– Jira/YouTrack — план и статус, не хранит спецификации. -
Трассируемость end-to-end.
Любой пункт в SRS мапится на задачу(и) в Jira и тест(ы) QA; из задачи — ссылка назад на SRS/диаграммы. -
Версионирование документации.
– Для «жизненно важных» артефактов — semver (например, SRS v1.3.0).
– Док-релизы синхронизированы с релизами ПО: есть теги в Git, есть «замороженные» PDF-срезы в Wiki. -
Минимум инструментов, максимум связей.
Лишние «блокноты» и дубли блокируются. Вводим обязательные поля/шаблоны: все страницы начинаются с блока Meta (версия, владелец, статус).
Confluence/Notion — как построить «витрину» артефактов
Структура пространства (пример Confluence)
/ Product X / 0. Onboarding (глоссарий, принципы, ссылки) / 1. Vision & Roadmap / 2. Business (BRD, BPMN/DMN, правила) / 3. System Requirements (SRS, NFR, C4, ER) / 4. Interfaces (OpenAPI, события, контракты) / 5. Testing & UAT (AC, BDD, планы) / 6. Observability & Ops (SLI/SLO, логи, алерты) / 7. Decisions (ADR) / 8. Change Log (история версий артефактов)
Метаданные каждой страницы (macro/шаблон «Meta»)
- Owner: роль/ФИО
- Version: semver (1.2.0)
- Status: Draft / Review / Approved / Deprecated
- Last Review: дата, ревьюер
- Links: Jira-эпики/фичи, Git-путь, прототипы
В Notion создайте базу «Docs» с полями: Type, Owner, Version, Status, Sprint, Git Link. Страницы связываются с реестром задач.
Макросы и правила
- Include Page для повторно используемых блоков (например, «Требования к ошибкам API»).
- Page Properties / Page Properties Report — таблица индекса артефактов (реестр SRS/ADR).
- Draw.io/PlantUML/Mermaid — хранить исходники диаграмм рядом с текстом; экспорт в репозиторий.
Права и ревью
- Папки /Decisions и /System Requirements — правка по PR-процессу (через черновики/ветки в репозитории), на странице — только просмотр и ссылки на канон.
- Ревью: минимум 2 пары глаз (Архитектор + Dev/QA Lead) перед «Approved».
Риск: «Wiki-гниение» (устаревшие страницы).
Как предотвращать: статусная панель «Docs Health»: % страниц с Last Review < 60 дней, число Deprecated без замены, SLA обновления.
Jira/YouTrack — типы задач, поля, связь с артефактами
Типы задач (рекомендация)
- Epic (бизнес-результат)
- Feature (объединяет сценарии)
- Story (пользовательский/технический сценарий)
- Task (аналитика/интеграция)
- Spike (исследование)
- Change Request (изменение требований/контрактов)
- Bug (дефект требований/контракта — помечаем меткой req-defect)
Обязательные поля для трассируемости
- Spec Link (url на раздел SRS/ADR)
- Contract Version (например, OpenAPI 2.4.0)
- Data Impact (Да/Нет, список сущностей)
- NFR Tag (latency/throughput/security…)
- Test Ref (ссылка на BDD/тест-набор)
Workflow (сокращённо)
Backlog → Ready (DoR) → In Progress → Ready for Test → UAT → Done
Переход в Ready — только при наличии Spec Link и AC.
Автоматизация: при смене версии OpenAPI в репозитории — авто-комментарий в связанные задачи (webhook/CI).
Miro/FigJam — правила диаграмм и прототипов
- Нотации и библиотеки: заведите библиотеку фигур BPMN/DMN/UML/C4, цветовые соглашения (не более 3-4 цветов; отдельный — для ошибок/исключений).
- Идентификаторы диаграмм: BPMN-PAY-001 Check-out flow v1.2 (в уголке — версия и владелец).
- Экспорт: SVG/PNG + исходник .drawio или .miro — в репозиторий /diagrams.
- Ссылки: на диаграмме — QR/URL на раздел SRS, в SRS — якорь на диаграмму.
Риск: несоответствие диаграмм и текста SRS.
Как предотвращать: PR-чеклист требует одновременного апдейта текста и диаграммы; лейбл diagram-changed в PR.
Репозитории и «docs-as-code»
Структура каталога (пример)
/docs
/srs
srs-payments.md
srs-returns.md
/brd
brd-payments.md
/vision
vision-product-x.md
/adr
ADR-0001-Idempotency-Key.md
/api
openapi.yml
schemas/Payment.json
/events
payment-captured.avsc
/diagrams
bpmn-checkout.drawio
c4-context.mmd
/bdd
payments.feature
/nfr
nfr-catalog.md
CHANGELOG.md
Ветки и PR-процесс
- Trunk-based с короткими ветками docs/feature/<ключ-задачи>.
- PR требует: ссылку на задачу, bump версии затронутых артефактов, changelog, список влияния на тесты/мониторинг.
Технологический минимум
- Markdown + Mermaid/PlantUML, OpenAPI/AsyncAPI, JSON-Schema/Avro.
- Pre-commit: валидация схем, линт OpenAPI, проверка битых ссылок.
- Git LFS — только для крупных изображений; старайтесь хранить диаграммы в текстовом виде (Mermaid/PlantUML).
Риск: «чёрные ящики» (PNG без исходника).
Как предотвращать: запрещено вливание изображений без исходников.
Версионирование документации (SemVer + релизы)
-
SemVer артефактов: MAJOR.MINOR.PATCH
– MAJOR: несовместимые изменения контрактов/моделей.
– MINOR: обратносуместимые добавления.
– PATCH: исправления опечаток/неоднозначностей, не меняющие смысл. -
Релиз документации = релизу ПО.
– Tag в Git (docs-v2025.08.1), PDF-срез SRS/BRD/ADR в Wiki в разделе /Change Log.
– Матрица соответствия: «Версия ПО → версии SRS/OpenAPI/Events».
Риск: версия API изменилась, а SRS — нет.
Как предотвращать: автоматизация CI — сравнивает openapi.yml с версией в SRS-header, фейлит билд.
Шаблоны артефактов (готовые скелеты)
Ниже — краткие шаблоны (Markdown). Их удобно держать в /docs/templates/ и генерировать из них новые документы.
Vision (Видение)
# Vision: <Продукт/Фича> **Owner:** <ФИО/роль> **Version:** 1.0.0 | **Status:** Draft | **Last Review:** <дата> ## 1. Контекст и проблема Кто пользователь, что болит, почему сейчас плохо. ## 2. Цели и метрики успеха Бизнес-метрики (конверсия, выручка, NPS), технические цели (SLO). ## 3. Область и ограничения Что входит/не входит, регуляторика, страны/каналы. ## 4. Гипотезы и риски Список ключевых допущений и рисков. ## 5. Дорожная карта (хайлевел) Эпики/кварталы; зависимости и внешние интеграции.
BRD (Business Requirements Document)
# BRD: <Фича/Направление> **Owner:** <ФИО> | **Version:** 1.1.0 | **Status:** Review ## 1. Бизнес-цели и пользователи Кто получает ценность и как измеряем. ## 2. Сценарии (as-is / to-be) Краткие описания, BPMN/ссылки. ## 3. Бизнес-правила (DMN) Таблицы решений / ограничения / примеры. ## 4. KPI/финмодель влияния Целевые значения и как считаем. ## 5. Риски и предположения Что может пойти не так, план «Б».
SRS (System Requirements Specification)
# SRS: <Компонент/Фича> **Owner:** SA <ФИО> | **Version:** 2.0.0 | **Status:** Approved | **Links:** Jira EPIC-123, OpenAPI 2.4.0 ## 1. Область и термины Границы системы, глоссарий, ссылки на Vision/BRD. ## 2. Функциональные требования Use Cases (основной/альтернативы), диаграммы последовательностей, BPMN/DMN ссылки. ## 3. Данные и модели ER-диаграмма, сущности, атрибуты, домены, справочники, миграции. ## 4. Интеграции REST/GraphQL/gRPC, события (AsyncAPI/Avro), идемпотентность, коды ошибок, лимиты, безопасность (OAuth2/JWT). ## 5. Нефункциональные требования (NFR) Производительность (p95/p99), надежность (RTO/RPO), безопасность, наблюдаемость (SLI/SLO, логи/метрики/трейсы), доступность/локализация. ## 6. Критерии приемки (AC) и BDD Given/When/Then для ключевых сценариев. ## 7. Ограничения и допущения Технические и организационные. ## 8. Трассируемость (RTM) Таблица: Требование → Задача → Тест → Мониторинг/Алерт. ## 9. Версионирование и изменения Ссылка на CHANGELOG, список breaking changes.
Decision Record (ADR)
# ADR-000X: <Короткое имя решения> **Status:** Proposed/Accepted/Deprecated | **Date:** <дата> | **Owner:** <ФИО> ## Context Факты, ограничения, альтернативы. ## Decision Сформулированное решение. ## Consequences Плюсы/минусы, влияние на архитектуру, кому сообщить. ## Alternatives Почему не выбрали A/B/C. ## Links Jira, PoC, метрики влияния.
Практический пример связности артефактов
Кейс: «Добавить Apple/Google Pay в чек-аут».
- Vision: цель увеличить конверсию оплаты на 2 п.п., сократить p95 до 3 c.
- BRD: сценарии выбора способа оплаты, правила 3DS/биометрии, ограничения регионов.
- SRS: POST /payments идемпотентный; события PaymentAuthorized/Captured/Failed; NFR — p95<3 c, retry 3 раза, circuit-breaker.
- ADR-0007: «Идемпотентность через Idempotency-Key vs deduplication в БД» — принято Idempotency-Key.
- Jira: EPIC-PAY-101, Feature-PAY-Add-Wallets; Story-API-CreatePayment; Task-Update-Monitoring.
- Miro/Confluence: BPMN «Оплата кошельком», DMN таблица «Правила 3DS», ссылки в SRS.
- Repo: /api/openapi.yml v2.4.0, /events/payment-captured.avsc, /bdd/payments.feature.
Типичные риски и как их закрывать
-
Дублирование артефактов между Wiki и Git.
→ Канон в Git, в Wiki — включения/вьюхи/ссылки. -
Устаревшие диаграммы.
→ PR-чеклист требует синхронного апдейта диаграммы и текста. -
Размытые роли и хаос правок.
→ Вводим статус «Approved», владелец страницы, регламент ревью. -
«PNG-архитектура».
→ Диаграммы — текстом (Mermaid/PlantUML) + экспорт; запрещаем бинарник без исходника. -
Нет метрик качества документации.
→ «Docs Health» дашборд: % страниц с review<60 дней, #req-defects, соответствие версий SRS vs OpenAPI.
Метрики (KPI) документации и процессов
- Req-defects rate: дефекты требований/релиз.
- Spec freshness: доля Approved с Last Review ≤ 60 дней.
- Traceability coverage: % требований в RTM, имеющих задачу и тест.
- Contract drift: случаи несовпадения версий SRS/OpenAPI (цель: 0).
- ADR cadence: >= 1 ADR на нетривиальное решение (покрытие ключевых решений ≥ 90%).
Вопрос–Ответ
Q1: Confluence или Notion?
A: Для крупных продуктовых/инженерных команд — Confluence из-за зрелых макросов, интеграции с Jira и управления правами. Notion удобен как «единая база», но сложнее в строгих процессах версионирования. Разрешается гибрид, но канон спецификаций — в Git.
Q2: Где хранить OpenAPI/события — в Wiki или Git?
A: Только в Git (текстовые файлы, проверяемые CI). В Wiki — рендер/ссылка.
Q3: Как обеспечить единый стиль документов?
A: Шаблоны + «Meta»-блок, линтеры (vale/textlint), ревью по чек-листу.
Q4: Можно ли вести SRS только в Jira?
A: Нет. Jira — трекинг задач. SRS — цельный документ с моделями, версионированием и связями. Храните в Git/Wiki, в Jira — ссылки.
Q5: Как поступать с крупными картинками и скринами?
A: Git LFS или внешний сторедж + ссылка. Но диаграммы — обязателен текстовый исходник.
Q6: Кто владеет ADR?
A: SA инициирует и ведёт, архитектор утверждает (или наоборот — по RACI). Статус ADR виден всем.
Q7: Как соотнести версии документации и релиза?
A: Матрица соответствия + теги Git + PDF-срез в Wiki. Без этого приёмка блокируется.
Q8: Что делать, если бизнес требует быстрых правок прямо в Wiki?
A: Вносим черновик со статусом Draft, параллельно готовим PR в репозиторий, после ревью — синхронизация и «Approved».
Домашнее задание (артефакты модуля)
- Завести пространство и развернуть «скелет» разделов (см. п.2.1).
- Подключить репозиторий /docs по структуре из п.5.1, настроить линтеры/CI.
- Настроить Jira: добавить поля Spec Link/Contract Version/Data Impact/NFR Tag/Test Ref.
- Создать шаблоны (Vision, BRD, SRS, ADR) в /docs/templates/ и зеркала-шаблоны в Wiki.
- Собрать первый ADR (любой нетривиальный выбор — например, стратегия идемпотентности или схема аутентификации API).
- Показать трассируемость: в одной Story указать Spec Link → в SRS поставить обратную ссылку → приложить BDD-файл.
Критерии зачёта: есть связность Wiki↔Jira↔Git, включены Meta-блоки, соблюдена структура, шаблоны доступны, создан ADR, включены минимум один BPMN/один OpenAPI/один BDD.
