Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Release vyšiel.
Release notes boli pripravené.
Používateľský manuál ostal starý.
Support manuál neobsahoval novú funkcionalitu.
Admin dokumentácia neobsahovala nové nastavenie.
A výsledok?
- Support odpovedal podľa starej verzie systému.
- Tester nevedel, čo má retestovať.
- Klient našiel inú funkcionalitu než tú, ktorú opisoval manuál.
- Nový kolega netušil, čo vlastne platí.
Release notes pritom tvrdili:
- „Pridaná podpora viacúrovňového schvaľovania.“
- „Aktualizovaný export.“
- „Rozšírené oprávnenia.“
Lenže nikto neaktualizoval dokumentáciu.
V projekte tak začali existovať dve reality:
- systém po release,
- a dokumentácia pred release.
Čo sa tu vlastne pokazilo (analýza systému)
Vo veľa firmách sa release notes berú ako:
- samostatný text,
- marketingový výstup,
- alebo len zoznam zmien.
Lenže release notes sú v skutočnosti:
- spojka medzi zmenou systému a zmenou dokumentácie.
Ak sa zmení systém, mali by sa aktualizovať:
- používateľské manuály,
- admin dokumentácia,
- support dokumentácia,
- technická dokumentácia,
- znalostná báza,
- onboarding materiály,
- checklisty,
- test cases.
Typický problém:
Vývoj dokončí funkcionalitu.
Release notes sa napíšu.
Dokumentácia sa „dorobí neskôr“.
A to „neskôr“ často nikdy nepríde.
Skutočné náklady (čas, chaos, riziko)
Neprepojené release notes a dokumentácia spôsobujú:
- neaktuálne manuály,
- nesprávne support odpovede,
- falošné bugy,
- zlé onboardingy,
- konflikty s klientom,
- chaos po release.
Typická situácia:
Release notes hovoria:
- „Pribudla povinná validácia.“
Používateľský manuál stále ukazuje starý postup.
Support podľa neho radí klientovi.
Používateľ tvrdí, že systém je pokazený.
A pritom problém nie je v systéme.
Problém je v neaktualizovanej dokumentácii.
To je veľmi častý zdroj:
- zbytočných incidentov,
- zbytočných telefonátov,
- zbytočných meetingov.
Minimálny model riešenia
Každá zmena vo release by mala mať odpoveď na otázku:
„Ktorú dokumentáciu táto zmena ovplyvňuje?“
Príklad:
Nová funkcionalita:
- aktualizovať user manuál,
- aktualizovať screenshoty,
- doplniť support scenáre,
- doplniť release notes,
- aktualizovať test cases.
Breaking change:
- aktualizovať admin dokumentáciu,
- API dokumentáciu,
- migračný postup,
- release notes.
Veľmi praktický model je mať v tasku alebo user story sekciu:
- Ovplyvnená dokumentácia:
- User guide
- Admin guide
- Support KB
- API dokumentácia
- Release notes
Takto sa dokumentácia nestáva „dobrovoľnou aktivitou“, ale súčasťou workflow.
Praktické pravidlo
Ak release notes opisujú zmenu, ktorú dokumentácia ešte nepozná, projekt je nekonzistentný.
Prepojenie na kvalitu a workflow
Release notes nemajú byť posledný krok pred release.
Mali by byť výsledkom procesu:
User story → Špecifikácia → Implementácia → Test → Dokumentácia → Release notes → Release
To znamená:
- dokumentácia vzniká priebežne,
- release notes len sumarizujú zmenu,
- nie sú jediným miestom, kde zmena existuje.
Veľa tímov robí opačný postup:
- najprv release,
- potom chaos,
- potom dodatočné dopisovanie dokumentácie.
To je drahé.
A hlavne neškálovateľné.
Ak firma chce:
- rýchly onboarding,
- kvalitný support,
- menej závislosti na senioroch,
- AI pripravenosť,
- stabilné releasy,
musí prepájať release notes s dokumentáciou systematicky.
Krátke zhrnutie
Release notes nie sú náhrada dokumentácie.
Sú:
- mapa zmien,
- vstup do aktualizácie dokumentácie,
- prepojenie medzi release a realitou projektu.
Ak sa po release zmení systém, ale nezmení dokumentácia, tím si vyrába budúci chaos.
Dobré firmy nepublikujú release notes oddelene od dokumentácie.
Publikujú ich ako súčasť jedného workflow.