Канарний реліз сервісу 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) Підсумок

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