Jak vytvořit interní wiki pro softwarovou aplikaci
Praktická struktura interní wiki: co dokumentovat, jak rozdělit obsah, určit vlastníky a udržet návody použitelné i po změnách v aplikaci.
Shrnutí a kontext
Dobrá interní wiki pomůže novému kolegovi pochopit aplikaci, vývojáři ji spustit a podpoře reagovat na problém. Nestačí do ní jen ukládat zápisy ze schůzek. Musí mít jasnou strukturu, vlastníky a pravidla údržby, jinak se z ní postupně stane archiv, kterému nikdo nevěří. Tento návod shrnuje běžnou praxi používanou při dokumentaci softwarových aplikací.
1. Začněte otázkami, na které má wiki odpovědět
Wiki není cílem sama o sobě. Jejím úkolem je zkrátit cestu k odpovědi a omezit závislost na tom, co si pamatuje jeden člověk. Než vytvoříte strom stránek, sepište si situace, ve kterých bude tým dokumentaci hledat.
Člověk, který aplikaci nezná, by měl z úvodních stránek zjistit: k čemu aplikace slouží, kdo za ni odpovídá, z čeho se skládá, jak ji spustit a nasadit, jak ověřit její stav a kde hledat pomoc při incidentu. Pokud tyto odpovědi vyžadují procházení chatu nebo dotaz na původního autora, v dokumentaci je mezera.
Dejte wiki kolegovi, který aplikaci nezná, a požádejte ho, aby podle ní našel vlastníka služby, spustil projekt a dohledal postup při výpadku. Místa, kde se musí doptat, jsou první kandidáti na opravu.
2. Co má interní wiki obsahovat
Obsah rozdělte podle potřeb čtenáře, ne podle organizační struktury firmy. Zavedené dokumentační přístupy rozlišují zejména vysvětlení, pracovní postupy, referenční informace a návody pro řešení problémů. Každý typ odpovídá na jinou otázku a neměl by být schovaný v jednom dlouhém dokumentu.
| Část wiki | Na co odpovídá | Typický obsah |
|---|---|---|
| Přehled aplikace | Co aplikace řeší a kdo ji vlastní? | Účel, uživatelé, vlastník, kontakty a stav životního cyklu |
| Architektura | Jak systém funguje a na čem závisí? | Kontextový diagram, hlavní komponenty, datové toky a externí služby |
| Vývoj | Jak začít bezpečně měnit kód? | Lokální spuštění, testy, konfigurace, větvení a práce s vývojovým prostředím |
| Nasazení | Jak dostat změnu do jednotlivých prostředí? | CI/CD, schvalování, migrace, ověření a návrat předchozí verze |
| Provoz | Jak poznáme a řešíme problém? | Monitoring, alerty, runbooky, zálohy, obnova a eskalace |
| Rozhodnutí | Proč je řešení právě takové? | Architektonická rozhodnutí, zvažované možnosti a jejich důsledky |
| Reference | Jaké jsou přesné hodnoty a rozhraní? | API, události, role, slovník pojmů a význam konfiguračních voleb |
3. Použijte jednoduchou a předvídatelnou strukturu
Domovská stránka wiki má být rozcestník, ne další obsáhlý manuál. Uveďte na ní krátký popis aplikace, vlastníka a odkazy na hlavní oblasti. Podrobnosti rozdělte do samostatných stránek, aby měly jasný účel a daly se samostatně vyhledat i udržovat.
Pro jednu aplikaci obvykle stačí základní členění: Začínáme, Architektura, Vývoj, Nasazení, Provoz, Rozhodnutí a Reference. Názvy přizpůsobte slovníku týmu, ale používejte je konzistentně. Stránku nazvanou „Postup nasazení do produkce“ najde člověk snáz než „Důležité informace 2“.
Nemíchejte bez rozmyslu různé typy dokumentace. Diátaxis rozlišuje výukové lekce, praktické návody, referenční dokumentaci a vysvětlení. Podobně GitLab pracuje s koncepty, úkoly, referencí a řešením problémů. Nemusíte tato označení zobrazovat čtenářům; důležité je, aby jedna stránka plnila jeden hlavní účel.
4. Pište stránky tak, aby podle nich šlo pracovat
Pracovní postup začněte výsledkem, ke kterému vede. Potom uveďte předpoklady, potřebná oprávnění a bezpečnostní omezení. Kroky napište v pořadí, v jakém se opravdu provádějí, a doplňte způsob ověření výsledku. U rizikových operací popište také návrat do bezpečného stavu.
Používejte krátké odstavce, výstižné nadpisy a stejné pojmy jako aplikace a tým. Příkaz, který lze zkopírovat, je užitečnější než jeho neurčitý popis. Snímek obrazovky přidejte jen tehdy, když ukazuje něco, co se textem vysvětluje obtížně; rozhraní se mění rychleji než dobře napsaný postup.
Pro provozní situace vytvářejte samostatné runbooky. Každý by měl popsat příznaky, dopad, první ověření, bezpečné kroky k nápravě, eskalaci a kontrolu po zásahu. Google SRE doporučuje aktuální a procvičované playbooky, protože dokument, o kterém služba neví nebo který nikdo nezkusil, při incidentu nepomůže.
5. Důležitá rozhodnutí uchovávejte jako ADR
Architektura není jen výsledný diagram. Stejně důležité je vědět, proč tým zvolil danou databázi, způsob autentizace nebo hranice mezi službami. Pro taková rozhodnutí používejte krátké záznamy ADR (Architecture Decision Record).
Každý záznam má obsahovat kontext, zvažované možnosti, přijaté rozhodnutí, jeho důsledky a stav. Přijaté ADR zpětně nepřepisujte. Když se rozhodnutí změní, vytvořte nové a označte, které původní rozhodnutí nahrazuje. Historie pak zůstane srozumitelná. Stejný postup doporučuje i Microsoft ve Well-Architected Frameworku.
6. Každá důležitá stránka potřebuje vlastníka
Za dokumentaci má odpovídat tým nebo role, ne člověk, který může odejít. U stránky uveďte vlastníka a podle možností také datum posledního věcného ověření. Samotné datum poslední úpravy nestačí: opravený překlep neznamená, že někdo zkontroloval platnost postupu.
Dokumentaci aktualizujte jako součást změny aplikace. Nové prostředí, jiný způsob nasazení, změna závislosti nebo nový alert jsou zároveň důvodem upravit příslušnou stránku. Kritické návody kontrolujte také po incidentu a při pravidelném provozním auditu. Nepoužívané stránky označte jako zastaralé nebo je archivujte, aby si nekonkurovaly s platným postupem.
GitLab staví dokumentaci do role jediného důvěryhodného zdroje a doporučuje poslat odkaz místo opakovaného vysvětlování stejné informace. Tento návyk funguje i v malém týmu: chybějící odpověď nejprve doplňte do wiki a teprve potom ji sdílejte.
Hesla, API klíče a jiné tajné hodnoty ukládejte do správce hesel nebo trezoru tajemství. Ve wiki může být postup a odkaz na příslušnou položku, ne samotné tajemství.
7. Určete, co je zdrojem pravdy
Ne všechno musí být ve wiki. README v repozitáři má rychle vysvětlit, co projekt dělá a jak s ním začít. Dokumentace těsně svázaná s konkrétní verzí kódu může být přímo v repozitáři. Úkoly a rozpracované návrhy patří do nástroje pro řízení práce. Hesla do správce hesel a aktuální provozní data do monitoringu. Wiki tyto zdroje propojuje a dodává jim kontext, ale nemá ručně kopírovat jejich obsah.
U každé informace zvolte jedno hlavní místo a z ostatních na něj odkazujte. Předejdete tak situaci, kdy existují tři různé postupy nasazení a nikdo neví, který platí. Backstage Software Catalog například odděluje katalog aplikací, jejich vlastníky a odkazy od samotné technické dokumentace.
Stejnou roli lehkého rozcestníku může u menších týmů plnit AboutTheApp: u aplikace lze držet odkazy na wiki, repozitář, monitoring nebo podporu, zatímco vlastní obsah zůstává v nástrojích, které jsou jeho zdrojem pravdy. Praktické nastavení popisuje článek Odkazy projektu.
8. Jak wiki zavést bez velkého dokumentačního projektu
Nesnažte se zdokumentovat všechno najednou. Začněte nejčastějšími a nejrizikovějšími situacemi: nástup nového člověka, lokální spuštění, nasazení a řešení výpadku. Zbytek doplňujte podle skutečných dotazů a změn v aplikaci.
- 1
Vytvořte jednu úvodní stránku
Popište účel aplikace, vlastníka a hlavní kontakty. Přidejte jednoduchý rozcestník do dalších částí.
- 2
Sepište čtyři základní dokumenty
Začněte lokálním spuštěním, přehledem architektury, nasazením a prvním runbookem pro nejčastější incident.
- 3
Určete vlastníky a pravidla změn
Ke každé oblasti přiřaďte odpovědný tým a do procesu změny aplikace přidejte kontrolu související dokumentace.
- 4
Ověřte wiki na skutečném úkolu
Nechte méně zkušeného kolegu provést postup bez ústního doprovodu. Opravte nejasnosti a chybějící předpoklady.
- 5
Průběžně odstraňujte duplicity
Když najdete stejnou informaci na více místech, určete hlavní zdroj a ostatní kopie nahraďte odkazy.
Časté otázky
Co má být první stránkou interní wiki?
Krátký přehled aplikace: její účel, hlavní uživatelé, odpovědný tým, kontakty a odkazy na architekturu, vývoj, nasazení, provoz a referenční dokumentaci.
Má být dokumentace ve wiki, nebo v repozitáři?
Dokumentace svázaná s konkrétní verzí kódu se obvykle lépe udržuje v repozitáři. Wiki je vhodná pro širší kontext, mezioborové postupy a obsah určený i lidem mimo vývoj. Důležité je zvolit pro každou informaci jeden hlavní zdroj a z ostatních míst na něj odkazovat.
Jak často interní wiki kontrolovat?
Při každé změně, která ovlivní popsaný postup, a po každém incidentu, který odhalí chybu v dokumentaci. Kritické provozní návody je vhodné navíc pravidelně projít a prakticky vyzkoušet.
Který nástroj pro interní wiki vybrat?
Vyberte nástroj, který tým skutečně používá, umí v něm vyhledávat a může v něm snadno opravovat obsah. Důležitější než značka nástroje jsou jasná struktura, vlastnictví, historie změn, oprávnění a pravidelná údržba.
Patří do interní wiki hesla a API klíče?
Ne. Tajné hodnoty patří do správce hesel nebo trezoru tajemství. Wiki má obsahovat bezpečný postup a případně odkaz na položku, ke které se přístup řídí v příslušném nástroji.
Ve zkratce
Užitečná interní wiki má předvídatelnou strukturu, rozlišuje různé typy dokumentace a u každé důležité stránky určuje vlastníka. Vzniká spolu se změnami aplikace, ověřuje se při skutečné práci a nekopíruje data z nástrojů, které jsou jejich zdrojem pravdy.
Máte dokumentaci, ale tým ji neumí rychle najít?
AboutTheApp může u každé aplikace propojit wiki, repozitář, monitoring a další důležitá místa v jednom rozcestníku.