Séria: Ako písať dokumentáciu a manuály v IT projekte](https://www.itpomocnicka.sk/tvorba-pouzivatelskej-a-technickej-dokumentacie/)
Reálny problém z praxe
Release je nasadený. Vývoj uzavrel ticket, testerka otestovala zmenu, product owner potvrdil správanie. Technicky je všetko hotové.
Potom príde otázka zo supportu:
„Čo sa vlastne zmenilo? Máme to niekde popísané?“
V release notes je jedna veta:
„Upravené správanie objednávkového procesu.“
Na prvý pohľad to vyzerá ako informácia. V praxi je to skoro nepoužiteľné.
Support nevie, čo má povedať zákazníkovi. Testerka nevie, či sa zmena týka iba jedného scenára alebo celého procesu. Projektový manažér nevie, či treba upozorniť konkrétnych používateľov. A keď sa o dva týždne objaví otázka, prečo sa systém správa inak, tím začne hľadať v tickete, komentároch, commitoch a pamäti ľudí.
Release notes mali byť jednoduchý zdroj informácie. Namiesto toho sa z nich stal ďalší nejasný text v systéme.
Čo sa tu vlastne pokazilo (analýza systému)
Najčastejšia chyba nie je to, že release notes chýbajú úplne. Často existujú. Problém je, že nie sú písané pre ľudí, ktorí ich reálne potrebujú používať.
Typické chyby:
- popis je príliš technický
- popis je príliš všeobecný
- chýba dopad na používateľa
- chýba informácia, koho sa zmena týka
- chýba rozdiel medzi starým a novým správaním
- chýba upozornenie na riziká alebo výnimky
- bugfix je popísaný tak neurčito, že sa nedá overiť
- zmeny sú pomenované podľa interných ticketov, nie podľa reality používateľa
Príklad zlej formulácie:
„Opravená validácia pri zadávaní údajov.“
Čo z toho vie support?
Skoro nič.
Nevie, ktorý formulár sa zmenil. Nevie, aké údaje sa validujú. Nevie, či používateľ uvidí novú hlášku. Nevie, či sa zmena týka všetkých zákazníkov alebo iba jednej konfigurácie.
Použiteľnejšia formulácia:
„V objednávkovom formulári sa upravila validácia telefónneho čísla. Systém už nepovolí uložiť číslo bez predvoľby krajiny. Používateľ pri neplatnom čísle uvidí hlášku: Telefónne číslo musí obsahovať predvoľbu krajiny.“
Toto už je informácia, s ktorou sa dá pracovať.
Testerka vie, čo overiť. Support vie, čo vysvetliť. Product owner vie, či treba pripraviť komunikáciu pre zákazníkov. A keď sa niekto o mesiac spýta, prečo sa zmenilo správanie formulára, odpoveď je dohľadateľná.
Skutočné náklady (čas, chaos, riziko)
Slabé release notes nevyzerajú ako veľký problém. V praxi však vytvárajú malé straty na viacerých miestach naraz.
Najčastejšie náklady:
- support sa pýta vývoja na veci, ktoré mali byť popísané
- testeri musia spätne zisťovať, čo presne bolo súčasťou releasu
- zákazník dostane nepresnú alebo neúplnú informáciu
- product owner nevie rýchlo vyhodnotiť dopad zmeny
- vznikajú falošné bugy, lebo nové správanie nebolo vysvetlené
- onboarding nových ľudí je pomalší, lebo história zmien je nečitateľná
- pri incidente sa stráca čas zisťovaním, či problém súvisí s posledným releasom
Praktická ukážka:
| Slabý zápis v release notes | Dopad na projekt |
|---|---|
| „Optimalizovaný export dát.“ | Nikto nevie, či sa zmenil obsah exportu, výkon alebo formát súboru. |
| „Opravený problém s faktúrami.“ | Support nevie, ktorých zákazníkov sa oprava týka. |
| „Pridaná nová funkcionalita pre administrátora.“ | Nie je jasné, kde sa nachádza, kto ju vidí a čo mení v procese. |
| „Úprava práv používateľov.“ | Vzniká riziko, že zákazník stratí alebo získa prístup bez vysvetlenia. |
| „Zmeny podľa ticketu ABC-123.“ | Bez otvorenia ticketu je zápis nepoužiteľný. |
Najväčšie riziko je, že tím si zvykne na nepresnosť. Release notes potom existujú iba formálne. Sú odškrtnuté, ale nepomáhajú rozhodovať, testovať ani podporovať prevádzku.
Minimálny model riešenia
Release notes nemusia byť dlhé. Nemusia byť literárne. Nemusia opisovať každý technický detail.
Musia však odpovedať na niekoľko praktických otázok:
- Čo sa zmenilo?
- Kde sa to zmenilo?
- Koho sa to týka?
- Ako sa správanie líši oproti predchádzajúcemu stavu?
- Čo má vedieť support, tester alebo používateľ?
- Je potrebná nejaká akcia po nasadení?
Minimálny model jednej položky v release notes môže vyzerať takto:
| Pole | Obsah |
|---|---|
| Oblasť systému | Objednávky |
| Typ zmeny | Úprava validácie |
| Čo sa zmenilo | Telefónne číslo musí obsahovať predvoľbu krajiny. |
| Dopad na používateľa | Bez predvoľby nepôjde objednávku uložiť. |
| Viditeľná zmena | Nová validačná hláška vo formulári. |
| Poznámka pre support | Pri hlásení od zákazníka skontrolovať formát telefónneho čísla. |
Konkrétna formulácia do release notes:
„Objednávky: Upravená validácia telefónneho čísla v objednávkovom formulári. Systém už nepovolí uložiť objednávku, ak telefónne číslo neobsahuje predvoľbu krajiny. Používateľ uvidí novú validačnú hlášku. Support môže pri problémoch so založením objednávky skontrolovať formát čísla ako prvý krok.“
Pri bugfixe môže byť model ešte jednoduchší:
- Problém pred opravou
- Opravené správanie
- Dopad na používateľa alebo zákazníka
- Ako overiť, že oprava funguje
Príklad:
„Fakturácia: Opravený problém, pri ktorom sa pri zákazníkoch s individuálnou zľavou nesprávne zaokrúhľovala výsledná suma. Po oprave sa zľava aplikuje pred výpočtom DPH. Zmena sa týka iba zákazníkov s individuálnou zľavou.“
Toto je krátke, ale použiteľné.
Prepojenie na kvalitu a workflow
Release notes by nemali vznikať až na konci, keď sa niekto pred nasadením spýta: „Čo tam máme napísať?“
Vtedy už tím často skladá informácie spätne. Vývoj si pamätá technické riešenie, testerka si pamätá scenáre, product owner si pamätá požiadavku, ale nikto nemá pripravenú jasnú vetu pre ľudí mimo implementácie.
Preto má zmysel prepojiť release notes s workflow ticketu.
Konkrétna formulácia do Definition of Done:
„Ticket je pripravený na release iba vtedy, ak obsahuje krátky popis zmeny pre release notes vrátane dopadu na používateľa alebo support.“
Toto pravidlo netreba robiť zložito. Stačí, aby mal ticket pole alebo komentár:
- Release note:
- Dopad na používateľa:
- Poznámka pre support:
- Potrebná komunikácia zákazníkovi: áno alebo nie
Príklad v Jire:
„Release note: V administrácii používateľov pribudla možnosť deaktivovať účet bez jeho vymazania. Deaktivovaný používateľ sa nevie prihlásiť, ale jeho história aktivít zostáva zachovaná.
Dopad na používateľa: Administrátor má novú akciu Deaktivovať účet.
Poznámka pre support: Pri požiadavke na zrušenie prístupu odporúčať deaktiváciu namiesto vymazania účtu.“
Takýto zápis pomáha aj testovaniu. Testerka vie, aká zmena má byť viditeľná navonok. Vie si položiť otázku, či release note zodpovedá reálnemu správaniu systému. Ak nie, je to signál, že niečo nie je zosúladené.
Release notes tým prestávajú byť administratívna povinnosť. Stávajú sa kontrolou, či tím vie zmenu vysvetliť.
A to je dôležité najmä pri väčších projektoch, kde existuje rozdiel medzi Core riešením a Custom úpravami. Ak release notes nepovedia, či sa zmena týka jadra systému alebo iba konkrétneho zákazníka, vzniká chaos pri podpore aj pri ďalšom vývoji.
Krátke zhrnutie
Najčastejšia chyba v release notes je, že popisujú zmenu z pohľadu tímu, ktorý ju implementoval, nie z pohľadu ľudí, ktorí ju musia používať, testovať alebo vysvetliť.
Dobré release notes nemusia byť dlhé. Musia byť konkrétne.
Mali by povedať:
- čo sa zmenilo
- kde sa to zmenilo
- koho sa to týka
- aký je dopad na používateľa
- čo má vedieť support alebo tester
- či je potrebná ďalšia akcia
Ak sa podľa release notes nedá pochopiť dopad releasu bez telefonátu seniorovi alebo vývojárovi, nie sú hotové. Sú iba formálne napísané.
Release notes sú malá časť dokumentácie, ale majú veľký dopad na kvalitu prevádzky. Pomáhajú tímu pochopiť, čo sa zmenilo, prečo sa to zmenilo a ako sa s tým má pracovať po nasadení.