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.
Súvisiace články a vzory
Prepojenie špecifikácie → test cases → manuál → release notes
- Nadväznosť špecifikácie, testov, manuálu a informácií o vydaní.
Ako písať používateľský manuál tak, aby odolal novým verziám
- Spôsob udržiavania používateľského manuálu pri zmenách produktu.
Verziovanie technickej dokumentácie
- Udržiavanie technickej dokumentácie pre jednotlivé verzie produktu.
Ktoré zmeny systému musia automaticky otvoriť úlohu na dokumentáciu
- Určenie zmien produktu, ktoré musia vyvolať aktualizáciu dokumentácie.
[Doplniť odkaz na článok.]
