Канареечный релиз сервиса Checkout

1) Зачем нужна документация операций

• превращает устные знания в повторяемые процедуры;
• задает границы ответственности и точки эскалации;
• служит источником доказательств для комплаенса и безопасности;
• ускоряет онбординг и уменьшает риски “узких горлышек”.

2) Таксономия документов (что к чему)

Policy (Политика): намерения и рамки (“что и почему”). Пример: Политика инцидент-менеджмента.
Standard (Стандарт): обязательные минимальные требования (“сколько”). Пример: сроки обновления TLS-сертификатов.
SOP / Procedure (Стандартная операционная процедура): последовательные шаги (“как”). Пример: Выпуск релиза с канареечным раскатом.
Runbook: пошаговые инструкции для типовых событий (алертов/операций). Пример: “API 5xx вырос — алгоритм действий”.
Playbook: набор решений по сценариям с вариантами и развилками. Пример: “Проблемы с платежным провайдером”.
KB (База знаний): ответы, FAQ, справки по инструментам.
Checklist: краткий список обязательных пунктов перед действиями.
Record / Evidence: журнал выполненных шагов, скриншоты/логи/подписи.

3) Принципы хорошей документации

Единый источник истины (SSOT). Документы не дублируются; распылять — значит устаревать.
Docs-as-Code. Храним в Git, проходим code-review, версии и диффы — видны.
Actionable-first. В начале — краткая карточка: когда запускать, кто владелец, что делать, критерии завершения.
Атомарность и адресность. Один документ — одна задача/процесс.
Обновляемость. Четкий владелец и SLA обновления (например, ежеквартально).
Наблюдаемость. Ссылки на дашборды/алерты/метрики встроены.
Безопасность-by-design. Классификация чувствительности, маскирование секретов, контроль доступа.

4) Жизненный цикл документа (Governance)

1. Инициирование: заявка/тикет → тип документа → владелец.
2. Черновик: шаблон, минимум примеров, ссылки на стандарты и SLO.
3. Ревью: техническое (SRE/платформа/безопасность), процедурное (менеджер процесса).
4. Публикация: в мастер-ветке, пометка версии/даты, присвоение статуса (active/experimental/deprecated).
5. Обучение/Коммуникация: анонс изменений, короткий тренинг/демо.
6. Ретроспектива: по итогам инцидентов/учений вносить правки.
7. Аудит и архив: неизменяемый след (кто/когда менял), устаревшие версии в архиве.

5) Структура SOP/Runbook (минимум)

1. Карточка: Название, Идентификатор, Версия/Дата, Владелец, Ответственные роли, Связанные политики/стандарты.
2. Когда применять: условия запуска (алерт/событие/окно работ).
3. Подготовка: права/инструменты/данные, риск-оценка, коммуникации.
4. Шаги: нумерованные, с командами/скриншотами/ожидаемыми результатами.
5. Критерии успеха/отката: четкие SLI/SLO-пороговые значения.
6. Эскалация: кто, когда и как (канал, телефон, провайдер).
7. Безопасность/комплаенс: чувствительные данные, запреты, записи действий.
8. Post-actions: закрытие тикетов, обновление статуса, сбор доказательств.
9. История изменений (changelog).

6) Стиль и правила оформления

Ясно и коротко: 1 шаг — 1 действие — 1 результат.
Императив: “Выполнить…”, “Проверить…”, “Откатить…”.
Скриншоты/команды: рядом с шагом; команды — копируемые блоки; примечайте ожидаемый вывод.
Вариативность: ветки “Если А → шаг X, если B → шаг Y”.
Когортность: где релевантно — укажите регионы/провайдеров/тенантов.
Локализация: ключевые документы — минимум на 2 языках; укажите статус переводов.
Теги и поиск: сервис, компонент, провайдер, тип инцидента, SLO, версия.

7) Docs-as-Code и инструменты

Хранилище: Git (main/feat/bugfix), PR-ревью, required checks.
Формат: Markdown/AsciiDoc; диаграммы в PlantUML/Mermaid; схемы JSON/YAML.
Публикация: статический сайт (Docusaurus/MkDocs) + поиск.
Верификация: CI-линт, тест ссылок, орфография, валидаторы блоков кода.
Интеграции: ChatOps-команды `/runbook open X`, отображение последней версии в алертах.
Связи: CMDB/сервис-каталог ↔ документация ↔ дашборды.

8) Контроль доступа и классификация

Классы: Public / Internal / Confidential / Restricted.
Разделение: публичные инструкции (общие статусы) vs закрытые (ключи, команды, диаграммы сети).
Секреты: запрещены в тексте; использовать секрет-хранилище и плейсхолдеры.
Аудит: журнал чтения/изменений для чувствительных SOP.

9) Связь с инцидентами и релизами

В каждом алерте — ссылка на релевантный runbook.
В каждом инциденте — ссылка на использованный SOP и чек отметок.
После RCA — обновление документов как CAPA-действие.
Перед релизом — checklist: готовность отката, флаги деградации, контакты провайдеров.

10) Минимальный обязательный набор (MVP-док-пакет)

Политика инцидент-менеджмента и Эскалации (SEV/P-уровни, тайминги).
Стандарт мониторинга и алерт-политик (burn rate, кворум).
SOP: релиз/откат (canary/blue-green), миграции БД (expand/contract).
Runbook: “Высокий error-rate”, “Рост p99”, “Падение успеха платежей”, “TLS/DNS проблема”.
Playbook внешних провайдеров (платежи/KYC/CDN): контакты, лимиты, фолбэки.
Политика управления секретами и доступами.
Шаблоны RCA и Post-mortem.
Таблица владельцев сервисов (RACI) и карта дашбордов.

11) Метрики качества документации (SLO документа)

Coverage: % критичных путей с SOP/Runbook.
Freshness: доля документов свежее N дней (например, 90).
Usability: % инцидентов, закрытых согласно runbook без эскалации.
Findability: медиана времени поиска нужного документа (по опросам/логам).
Defect rate: количество замечаний на ревью/100 документов.
Adoption: доля алертов с корректной ссылкой на runbook.
Compliance evidence rate: % задач с приложенными доказательствами.

12) Чек-листы

Чек-лист создания SOP

• Определен владелец и целевая аудитория.
• Есть условия запуска и стоп-критерии.
• Шаги воспроизводимы, проверены другим инженером.
• Встроены ссылки на дашборды/алерты/инструменты.
• Без секретов; есть плейсхолдеры и ссылка на vault.
• Описаны откат и эскалация.
• Добавлен чек-лист “после действий”.
• Версия, дата, changelog.

Чек-лист ревью

• Документ соответствует таксономии (не смешивает политику и шаги).
• Язык простой, императивный, без двусмысленностей.
• Команды проверены в “сухом прогоне”/стейдже.
• Риски и контрольные точки указаны.
• Доступность (Internal/Restricted) корректна.
• Пройдены линтеры/валидаторы в CI.

13) Локализация, версия и доступность

Версия: `MAJOR.MINOR.PATCH`, где MAJOR ломает совместимость процессов.
Языки: отмечайте “источниковый” язык и статус переводов (up-to-date/needs review).
Форм-фактор: мобильное/ночное отображение для on-call, печатные карточки IC.

14) Док-автоматизация (из практики)

Генерация каркасов SOP из шаблонов CLI (`doc new sop --service=payments`).
Авто-вставка ссылок на последние дашборды по тегам сервиса.
Боты-напоминалки о просроченных документах (freshness SLA).
Экспорт пакета Evidence за период (PDF/ZIP) для аудита.
Связывание тикетов инцидентов с версией документов, использованных при решении.

15) Безопасность и комплаенс

Обязательные разделы “Риски” и “Контрольные мероприятия”.
Хранение evidence в неизменяемом архиве с подписями/хэшами.
Привязка к нормативам (например, сроки уведомлений/ретенции), явные владельцы соответствия.

16) Анти-паттерны

“Вики-лабиринт” без владельцев и дат обновления.
Политики, смешанные с командами — никто не найдет, что выполнять.
Документы без контекста (нет SLO, дашбордов, эскалаций).
Скриншоты с секретами или инструкции “кликни сюда” без CLI-альтернатив.
“Один гуру знает как” — tribal knowledge без фиксации.
Архивные PDF как единственная версия — не редактируются, не ищутся.

17) Шаблоны (фрагменты)

Шапка SOP (пример)

SOP-ID: OPS-REL-001

18) Встраивание в ежедневную работу

Еженедельные doc-кружки: разбор 1–2 документов, актуализация, обмен опытом.
Game-days: проверка реальности SOP/Runbook в симуляциях.
Онбординг: маршрут новичка через набор обязательных документов + короткие квизы.
Док-долг: бэклог улучшений с приоритизацией (impact × effort).

19) Итог

Документация операций — это не архив, а рабочий инструмент. Когда она ведется как код, имеет владельцев, метрики свежести и встроена в инциденты, релизы и обучение, организация становится предсказуемой: меньше ошибок, быстрее реакции, понятная ответственность и готовность к аудиту. Пишите коротко, обновляйте регулярно, автоматизируйте рутину — и документация начнет экономить время и деньги.