Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Nový tester dostane úlohu overiť funkcionalitu.
Otvorí dokumentáciu a nájde:
- pôvodný manuál z roku 2022,
- aktualizáciu z roku 2023,
- release notes z roku 2024,
- ďalšie doplnenie v Confluence,
- poznámku v Jire,
- workaround v support databáze.
Po hodine štúdia stále nevie odpovedať na jednoduchú otázku:
„Ako to funguje dnes?“
Všetky informácie sú síce niekde zapísané, ale nikto nevie, ktorá verzia je aktuálna.
A to je jeden z najčastejších problémov dokumentácie.
Nie chýbajúca dokumentácia.
Príliš veľa historickej dokumentácie bez jasného oddelenia od aktuálneho stavu.
Čo sa tu vlastne pokazilo (analýza systému)
Mnohé firmy dokumentáciu nearchivujú.
Namiesto toho:
- pridávajú nové kapitoly,
- dopisujú poznámky,
- ukladajú nové verzie vedľa starých,
- vytvárajú ďalšie dokumenty.
Po niekoľkých rokoch vznikne informačná skládka.
Typické príznaky:
- viacero dokumentov opisuje tú istú funkcionalitu,
- nie je jasné, ktorý dokument platí,
- staré screenshoty vyzerajú ako aktuálne,
- workaroundy zostanú v dokumentácii aj po oprave chyby,
- release notes sa používajú ako náhrada dokumentácie.
Problém nie je nedostatok informácií.
Problém je nedostatok riadenia informácií.
Skutočné náklady (čas, chaos, riziko)
Neudržiavaná história spôsobuje:
- pomalší onboarding,
- dlhšie analýzy incidentov,
- nesprávne testovanie,
- zlé rozhodnutia,
- vyššiu závislosť na senioroch.
Typická situácia:
Používateľ nahlási problém.
Support nájde článok z roku 2021.
Podľa neho odporučí riešenie.
Lenže funkcionalita sa medzičasom trikrát zmenila.
Výsledok:
- problém sa nevyrieši,
- klient je nespokojný,
- support stráca čas,
- vývoj rieši zbytočnú eskaláciu.
To všetko preto, že staré informácie vyzerali ako aktuálne.
Minimálny model riešenia
Dokumentácia musí jasne odlišovať:
- aktuálny stav,
- historické informácie.
Najjednoduchší model:
Aktuálna dokumentácia
Obsahuje iba:
- aktuálne funkcionality,
- aktuálne postupy,
- aktuálne screenshoty,
- aktuálne konfigurácie.
Človek musí vedieť:
„Toto platí dnes.“
Archív
Obsahuje:
- staré verzie dokumentov,
- ukončené funkcionality,
- historické release notes,
- staré návody,
- migračné informácie.
Človek musí vedieť:
„Toto je história.“
Tieto dva svety sa nesmú miešať.
Praktický príklad
Zlé riešenie:
- Manuál v3
- Manuál_v3_final
- Manuál_v3_final_novy
- Manuál_v3_final_final
Lepšie riešenie:
- Používateľský manuál (aktuálny)
- Archív dokumentácie
- verzia 3.0
- verzia 2.5
- verzia 2.0
Používateľ okamžite vie, kde hľadať.
Prepojenie na kvalitu a workflow
História má byť dohľadateľná.
Nemá byť súčasťou každodennej práce.
Release notes sú dobrý príklad.
Mnohé firmy majú stovky strán historických zmien.
Ak však človek potrebuje zistiť aktuálne správanie systému, nemal by čítať tri roky release notes.
Mal by otvoriť aktuálnu dokumentáciu.
Release notes odpovedajú na otázku:
„Čo sa zmenilo?“
Dokumentácia odpovedá na otázku:
„Ako to funguje dnes?“
To sú dve rôzne veci.
Preto je dôležité mať workflow:
User story → Implementácia → Test → Aktualizácia dokumentácie → Release notes → Archivácia starých informácií
Nie:
User story → Release notes → ďalšie release notes → ďalšie release notes → chaos.
Krátke zhrnutie
Dobrá dokumentácia nepotrebuje len vzniknúť.
Musí vedieť aj starnúť.
Ak sa neoddeľuje aktuálny stav od histórie, projekt postupne vytvára informačný šum.
Používatelia, support, testeri aj noví kolegovia potom trávia viac času hľadaním správnej informácie než samotnou prácou.
Dokumentácia má odpovedať na otázku:
„Ako to funguje dnes?“
História má zostať dostupná.
Ale nemá prekážať pri hľadaní odpovede.