Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Firma vydá novú verziu.
Na webe sa objaví krátky text:
„Zlepšili sme výkon a opravili chyby.“
Support však rieši desiatky otázok:
- „Prečo sa mi zmenil postup?“
- „Prečo mi nejde odoslať objednávka?“
- „Kde zmizla funkcia?“
Interný tím pritom vie, že:
- pribudla validačná podmienka
- zmenil sa workflow
- jedna funkcia bola dočasne vypnutá
Lenže tieto informácie sa nedostali von.
A opačný extrém:
Interné release notes obsahujú technické detaily, ktoré sa omylom dostanú ku klientovi:
- názvy databázových tabuliek
- workaroundy
- bezpečnostné slabiny
Výsledok:
buď informácií málo, alebo príliš veľa – a obe varianty sú problém.
Čo sa tu vlastne pokazilo
Firma nemá oddelené:
- čo potrebuje vedieť interný tím
- čo potrebuje vedieť zákazník
Release notes sa berú ako jeden dokument pre všetkých.
Lenže to nefunguje.
Interné a verejné release notes majú úplne iný cieľ.
Skutočné náklady
Ak nie je rozdiel jasný:
- support improvizuje, lebo nevie o zmenách
- tester nevie, čo je očakávané správanie
- obchod komunikuje nepresné informácie
- používateľ stráca dôveru („zase sa niečo zmenilo bez vysvetlenia“)
A naopak:
- firma môže nechtiac zverejniť citlivé informácie
- klient dostane detaily, ktoré nevie interpretovať
- vzniká šum namiesto jasnej komunikácie
Minimálny model riešenia
Zaveď dve vrstvy release notes.
1. Interné release notes
Pre koho:
- vývoj
- testeri
- support
- produktový tím
Obsah:
- presný popis zmien (aj technický)
- odkazy na user story, bugy, tasky
- kontext: prečo sa zmena robila
- dopad na testovanie
- dopad na support
- známe problémy a workaroundy
- označenie Core vs Custom
Príklad:
„Validácia nákladového strediska bola sprísnená. Pri klientovi XY je pole povinné. Workaround: dočasne možné vyplniť hodnotu ‘000’.“
2. Verejné release notes
Pre koho:
- koncový používateľ
- administrátor u klienta
- obchodný partner
Obsah:
- nové funkcionality
- zmeny správania (zrozumiteľne)
- opravené chyby (len relevantné)
- breaking changes
- čo má používateľ urobiť inak
Príklad:
„Pri schvaľovaní objednávky je po novom povinné vyplniť nákladové stredisko.“
Bez workaroundov. Bez interných poznámok.
Prepojenie na kvalitu a workflow
Rozdelenie musí vzniknúť už počas práce na úlohe.
Nie na konci release.
Pri každej zmene by malo padnúť rozhodnutie:
- ide to do interných release notes?
- ide to do verejných release notes?
- ide to do oboch?
- je to Core alebo Custom?
Konkrétna formulácia do DoD:
Každá zmena musí mať vyhodnotený dopad na interné a verejné release notes. Bez toho sa úloha nepovažuje za dokončenú.
Týmto:
- support dostane informácie včas
- dokumentácia sa aktualizuje priebežne
- používateľ dostane len to, čo potrebuje
Krátke zhrnutie
Interné release notes vysvetľujú realitu systému.
Verejné release notes komunikujú zmenu používateľovi.
Ak sa tieto dve vrstvy zmiešajú, vznikne buď chaos, alebo riziko.
Ak sú oddelené a prepojené s workflow, release notes prestanú byť formalita a začnú fungovať ako nástroj riadenia kvality.