Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Release je nasadený, úlohy sú zatvorené, bugy opravené. A potom príde otázka:
„Čo sa vlastne v tejto verzii zmenilo?“
Vývoj vie svoje. Tester si pamätá testované scenáre. Support zachytí prvé otázky používateľov. Obchodník povie klientovi niečo z hlavy. Používateľ si všimne zmenu až vtedy, keď mu prestane sedieť postup v manuáli.
A niekde medzi tým chýbajú release notes.
Nie ako marketingový oznam. Nie ako zoznam ticketov. Ale ako praktický prehľad zmien, ktorý povie tímu aj zákazníkovi, čo nová verzia prináša, čo opravuje, čo mení a na čo si treba dať pozor.
Čo sa tu vlastne pokazilo
Release notes sa často nerobia priebežne. Vznikajú až na konci release, keď už si každý len matne pamätá, čo sa riešilo.
Typické problémy:
- zmeny sú len v Jire, ale nikto ich nepreložil do zrozumiteľného textu
- bugy sú zatvorené, ale nie je jasné, či ich treba komunikovať používateľom
- nové funkcionality sú popísané technicky, nie používateľsky
- breaking changes nie sú označené
- interné a verejné informácie sú pomiešané
- dokumentácia sa po release neaktualizuje
Release notes sú pritom most medzi vývojom, testovaním, dokumentáciou, supportom a používateľom.
Skutočné náklady
Keď release notes chýbajú alebo sú slabé, vzniká chaos.
Support nevie, čo má vysvetľovať. Tester nevie, či zmena bola plánovaná alebo je to nový bug. Používateľ nevie, prečo sa mu zmenil postup. Administrátor nevie, či musí niečo nastaviť. Dokumentácia zostane v starej verzii.
Najhorší prípad je tichá zmena správania systému.
Funkcia vyzerá rovnako, ale správa sa inak. Nikto to nekomunikuje. Používateľ nahlási bug. Support eskaluje na vývoj. Vývoj odpovie: „To je predsa podľa novej verzie.“
Toto nie je technický problém. Toto je problém komunikácie zmeny.
Minimálny model riešenia
Release notes nemusia byť dlhé. Musia byť použiteľné.
Minimálny obsah jednej verzie:
| Časť | Čo má obsahovať |
| Verzia | číslo verzie, dátum vydania |
| Nové funkcionality | čo pribudlo a pre koho |
| Zmenené správanie | čo funguje inak než predtým |
| Opravené chyby | len tie, ktoré sú relevantné pre používateľa alebo support |
| Breaking changes | zmeny, ktoré môžu ovplyvniť existujúce procesy |
| Dopad na dokumentáciu | ktoré manuály alebo články treba aktualizovať |
| Dopad na support | čo má support vedieť pri prvých otázkach |
| Známé obmedzenia | čo ešte nie je vyriešené alebo má limit |
Príklad formulácie:
Nevhodné:
„Upravený workflow schvaľovania.“
Lepšie:
„Pri schvaľovaní objednávky sa po novom kontroluje aj vyplnenie nákladového strediska. Ak pole nie je vyplnené, systém objednávku nepustí do ďalšieho kroku.“
Ešte lepšie pre interné release notes:
„Zmena sa týka klientov s aktívnym modulom Nákladové strediská. Treba aktualizovať používateľský manuál, test cases pre schvaľovanie objednávok a support článok k chybe pri odoslaní objednávky.“
Prepojenie na kvalitu a workflow
Release notes nemajú vzniknúť až po release. Majú byť súčasťou workflow.
Už pri user story alebo tasku by malo byť jasné:
- mení sa správanie systému?
- treba aktualizovať používateľský manuál?
- týka sa to administrátora?
- musí o tom vedieť support?
- ide o Core alebo Custom zmenu?
- je to verejná informácia alebo len interná?
Konkrétna formulácia do Definition of Done:
Úloha nie je hotová, kým je vyhodnotené, či zmena patrí do release notes. Ak zmena ovplyvňuje používateľa, administrátora, support alebo existujúcu dokumentáciu, musí byť pripravený text pre interné alebo verejné release notes.
Release notes sú kontrolný bod kvality. Núti tím pomenovať, čo sa zmenilo a koho sa to týka.
Krátke zhrnutie
Release notes nie sú ozdobný text k vydaniu novej verzie.
Sú praktický prehľad zmien, ktorý pomáha tímu aj používateľom pochopiť, čo sa v systéme zmenilo, prečo je to dôležité a čo treba upraviť v práci, testoch, supporte alebo dokumentácii.
Ak firma nevie napísať release notes, často to znamená, že nemá poriadok ani v samotnom release procese. Release notes len odhalia, kde sa informácie stratili.
Zdrojovo nadväzuje na mapu série k oblasti Release notes.