73. Tvorba interní dokumentace a runbooků

Úvod a kontext

Modul 14 zmínil runbooky jako klíčovou pomůcku pro on-call inženýra
v krizové situaci a postmortemy jako dokument popisující incident.
Tato lekce se věnuje dokumentaci obecněji — jaké typy dokumentace
tým potřebuje, jak ji psát, aby ji lidé skutečně používali, a jak ji
udržet aktuální, což bývá ve skutečnosti těžší problém než samotné
sepsání.

Teorie

Proč dokumentace selhává

Nejčastější příčina, proč dokumentace v týmech nefunguje, není
"nikdo neumí psát" — je to, že dokumentace zastará a lidé jí
přestanou věřit. Jakmile se jednou stane, že dokumentace řekla něco
jiného, než byla realita (viz "zastaralý rollback runbook" z
postmortemu v modulu 14), lidé ji přestanou konzultovat úplně, i
poté, co se zbytek aktualizuje — ztráta důvěry se obtížně obnovuje.
Druhá častá příčina je, že dokumentace vzniká jako jednorázový
projekt ("tenhle týden napíšeme dokumentaci"), ne jako průběžná
součást práce.

Druhy dokumentace a jejich účel

• Runbook — krok za krokem postup pro konkrétní operační
  situaci (viz modul 14). Cílová skupina: on-call inženýr pod
  časovým tlakem. Musí být stručný, akční, bez zbytečného kontextu.
• Architektonická dokumentace — jak systém funguje a proč byl
  navržen právě takto (často jako ADR — Architecture Decision
  Record, viz níže). Cílová skupina: nový člen týmu, nebo někdo, kdo
  se ptá "proč to takhle je" o rok později.
• Onboarding dokumentace — jak se novému člověku nastavit
  prostředí, získat přístupy, provést první nasazení. Cílová
  skupina: lidé v prvním týdnu.
• API/rozhraní dokumentace — jak systém používat zvenčí (formát
  požadavků, autentizace, chybové kódy). Cílová skupina: jiné týmy
  nebo externí konzumenti.
• Provozní příručky/postupy (playbooks) — širší než runbook,
  popisují opakující se procesy (jak nasadit novou verzi, jak
  přidat nový cluster). Cílová skupina: kdokoliv v týmu.

Smíchání těchto typů do jednoho neuspořádaného dokumentu je běžná
chyba — onboarding dokument plný hlubokých architektonických detailů
odradí nováčka, zatímco runbook s dlouhým úvodem do historie systému
zpomalí on-call inženýra přesně ve chvíli, kdy potřebuje rychlost.

Architecture Decision Records (ADR)

ADR je krátký dokument zaznamenávající jedno konkrétní architektonické
rozhodnutí — ne jak systém funguje dnes, ale proč bylo rozhodnuto
tak, jak bylo, v daný okamžik, s jakými alternativami se počítalo.
Typická struktura ADR:

# ADR-014: Použití PostgreSQL místo MongoDB pro hlavní datové úložiště

## Stav
Přijato (2024-02-10)

## Kontext
Potřebujeme zvolit primární databázi pro novou službu objednávek.
Data mají jasně definovanou relační strukturu (objednávky, položky,
zákazníci) s potřebou silné konzistence u plateb.

## Zvažované možnosti
1. PostgreSQL — relační, silné transakce, tým má zkušenosti.
2. MongoDB — flexibilní schéma, ale slabší garance konzistence
   napříč více dokumenty bez dalších opatření.

## Rozhodnutí
Zvolen PostgreSQL kvůli požadavku na silnou transakční konzistenci
u plateb a relační povaze dat.

## Důsledky
Musíme řešit schema migrace (viz Django migrace). Flexibilita
schématu bude nižší než u MongoDB, což akceptujeme jako přijatelný
kompromis vzhledem k povaze dat.

ADR má obrovskou hodnotu o rok nebo dva později, kdy si nikdo
nepamatuje, proč bylo rozhodnuto zrovna takto — bez ADR tým riskuje,
že rozhodnutí znovu a zbytečně rozporuje, nebo ho naopak nevědomky
poruší, protože důvod už nikdo nezná.

Docs as code

Nejúčinnější praktický princip proti "zastarávání" dokumentace je
docs as code — dokumentace se píše jako Markdown soubory přímo
v Git repozitáři (viz modul 3), ideálně ve stejném pull requestu jako
kódová změna, kterou popisuje. Výhody:

• Verzování a historie. git log/git blame ukáže, kdy a proč
  se dokumentace změnila, stejně jako u kódu.
• Review v pull requestu. Změna dokumentace prochází stejným
  code review procesem jako kód — kolega si všimne, že dokumentace
  neodpovídá nové implementaci, přímo v rámci review.
• Blízkost ke kódu. Dokumentace žije ve stejném repozitáři jako
  kód, který popisuje, takže je snazší si vytvořit návyk "měním
  chování → měním i dokumentaci ve stejném PR", než když
  dokumentace žije v odděleném wiki nástroji, na který se snadno
  zapomene.
• CI kontroly (modul 9) mohou automaticky ověřit základní věci —
  např. že odkazy v dokumentaci nevedou na neexistující stránky,
  nebo že příklady kódu projdou syntaktickou kontrolou.

Nevýhoda je vyšší vstupní bariéra pro netechnické čtenáře (Markdown
v Gitu je méně přívětivý než WYSIWYG wiki) — proto se ve firmách
často kombinuje: technická dokumentace jako docs as code, zatímco
netechnická dokumentace (HR procesy apod.) zůstává v běžném wiki
nástroji.

Jak udržet dokumentaci aktuální

• Vlastnictví (ownership). Každý důležitý dokument by měl mít
  jasného vlastníka (tým nebo osobu), který je zodpovědný za jeho
  aktuálnost — dokumentace "bez majitele" je nejčastější kandidát na
  zastarání.
• Pravidelná revize. Kritické runbooky a onboarding dokumentace
  se hodí kontrolovat v pravidelném intervalu (např. čtvrtletně) —
  totéž doporučení jako u testování DR plánu z lekce 70: netestovaný
  (nekontrolovaný) dokument je stejné riziko jako netestovaná záloha.
• "Dokumentace jako definice hotovo". Zahrnout aktualizaci
  dokumentace do definice "hotovo" u úkolu (definition of done) —
  úkol, který mění chování systému, není hotový, dokud není
  aktualizovaná i příslušná dokumentace.
• Odstraňování zastaralé dokumentace. Smazaný nebo jasně
  označený "zastaralé, nepoužívat" dokument je lepší než dokument,
  který tiše zavádí na scestí — v docs-as-code modelu je smazání
  stejně snadné jako u kódu (git rm).

Praktický příklad

Ukázka runbooku psaného v duchu docs-as-code principů — stručný,
akční, uložený v docs/runbooks/vysoka-latence-api.md v témže
repozitáři jako aplikace, kterou popisuje:

# Runbook: Vysoká latence API

**Poslední revize:** 2024-03-01 (@jana) — kontrolováno čtvrtletně
**Alert:** `HighAPILatency` (Prometheus, viz modul 12)

## Rychlá diagnostika (prvních 5 minut)
1. Otevři dashboard: https://grafana.interni/d/api-latency
2. Zkontroluj, zda latence roste u všech endpointů, nebo jen
   u konkrétního — pokud jen u jednoho, jde pravděpodobně
   o pomalý databázový dotaz, ne systémový problém.
3. Zkontroluj využití connection poolu databáze (viz incident
   z modulu 14, lekce 67) — pokud je nad 90 %, jde
   pravděpodobně o vyčerpání poolu.

## Obvyklé příčiny a mitigace
| Příznak | Pravděpodobná příčina | Mitigace |
|---|---|---|
| Latence roste u všech endpointů | Přetížená databáze | Zkontroluj pomalé dotazy, zvaž rollback poslední změny |
| Latence roste jen po nasazení | Regrese v novém kódu | Rollback (viz modul 9, CD strategie) |
| Latence roste postupně, ne skokem | Rostoucí zátěž, škálování nestačí | Zkontroluj HPA (modul 8), případně navyš maxReplicas |

## Eskalace
Pokud se problém nevyřeší do 15 minut, eskaluj podle politiky
v modulu 14 (lekce 68).

Shrnutí

Dobrá interní dokumentace rozlišuje typy (runbook, architektonická
dokumentace, onboarding, API dokumentace) podle cílové skupiny a
situace, ve které se čte. ADR zaznamenávají důvody rozhodnutí, ne
jen aktuální stav. Princip docs as code — psaní dokumentace jako
verzovaných Markdown souborů v Gitu, ideálně ve stejném pull
requestu jako související kódová změna — je nejúčinnější praktický
nástroj proti nejčastějšímu selhání dokumentace: ztrátě aktuálnosti
a s ní i důvěry čtenářů.

Kontrolní otázky

1. Proč je nejčastější příčinou selhání dokumentace ztráta aktuálnosti,
   a ne špatné psaní jako takové?
2. Co zaznamenává ADR, co běžná architektonická dokumentace obvykle
   nezaznamenává?
3. Jaké jsou hlavní výhody principu "docs as code" oproti oddělenému
   wiki nástroji?
4. Mini cvičení: navrhněte, jak byste do "definice hotovo" (definition
   of done) vašeho týmu zapracovali povinnost aktualizovat dokumentaci
   — jakou konkrétní formulaci byste použili?