Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Používateľ otvorí release notes a prečíta si:
- „Vylepšili sme používateľský zážitok.“
- „Optimalizovali sme systém.“
- „Pridali sme nové možnosti práce s dátami.“
- „Zvýšili sme stabilitu aplikácie.“
Lenže nikto nevie:
- čo sa reálne zmenilo,
- koho sa zmena týka,
- či musí niečo upraviť,
- či sa zmenilo správanie systému,
- či hrozí problém po upgrade.
Výsledok?
Support dostáva otázky, tester nevie čo retestovať a admin netuší, či release obsahuje rizikovú zmenu.
Také release notes neplnia svoju funkciu.
Sú to marketingové texty, nie prevádzková informácia.
Čo sa tu vlastne pokazilo (analýza systému)
Mnohé firmy píšu release notes ako reklamný text.
Dôvod býva jednoduchý:
- release notes píše marketing,
- alebo človek, ktorý nepozná technický dopad zmien,
- alebo tím nemá definované pravidlá, čo sa má do release notes zapisovať.
Potom vznikajú formulácie typu:
- „Zlepšili sme výkon.“
- „Optimalizovali sme databázu.“
- „Pridali sme nové funkcionality.“
To však nie je informácia použiteľná pre:
- používateľa,
- admina,
- support,
- testera,
- integrátora.
Release notes majú odpovedať na otázku:
„Čo sa zmenilo a aký to má dopad?“
Nie:
„Ako pekne to znie.“
Skutočné náklady (čas, chaos, riziko)
Nejasné release notes spôsobujú:
- zbytočné incidenty,
- falošné bugy,
- nepochopenie zmien,
- chaos pri podpore,
- neúplné retesty,
- konflikty medzi klientom a dodávateľom.
Typický scenár:
Vo verzii sa zmení validácia formulára.
Release notes napíšu:
- „Vylepšená validácia údajov.“
Ale nikto nepovie:
- ktoré polia sa zmenili,
- čo je teraz povinné,
- ktoré staré dáta už neprejdú,
- či to ovplyvní integrácie.
Používateľ potom považuje nové správanie za bug.
Support nevie, či ide o chybu alebo plánovanú zmenu.
Tester spätne zisťuje, čo sa vlastne malo retestovať.
Minimálny model riešenia
Každá položka v release notes by mala obsahovať minimálne:
- čo sa zmenilo,
- koho sa zmena týka,
- aký je dopad,
- či je potrebná akcia používateľa/admina,
- či ide o breaking change.
Zlá formulácia:
- „Optimalizovaný export.“
Lepšia formulácia:
- „Export objednávok teraz generuje CSV v UTF-8 namiesto Windows-1250. Integrácie spracúvajúce starý encoding je potrebné upraviť.“
Zlá formulácia:
- „Zlepšené prihlasovanie.“
Lepšia formulácia:
- „Po 5 neúspešných pokusoch sa účet dočasne zablokuje na 15 minút.“
To je informácia, s ktorou vie pracovať:
- používateľ,
- support,
- tester,
- admin,
- bezpečnostný tím.
Praktické pravidlo
Ak sa po prečítaní release notes nedá odpovedať na otázku:
„Čo mám teraz urobiť alebo skontrolovať?“
tak release notes nie sú dostatočne konkrétne.
Prepojenie na kvalitu a workflow
Release notes nemajú vzniknúť ručne „na konci“.
Mali by byť výsledkom workflow:
User story → Task → Bug → Verzia → Release notes
Ak tím:
- správne používa verzie,
- zapisuje dopady zmien,
- označuje breaking changes,
- prepája dokumentáciu s taskmi,
tak release notes vznikajú prirodzene.
Ak nie, človek pred release improvizuje a skladá texty z commitov alebo z pamäte seniora.
To je presne moment, kde sa ukáže kvalita procesu firmy.
Release notes sú v skutočnosti:
- zrkadlo projektového workflow,
- zrkadlo kvality dokumentácie,
- zrkadlo komunikácie v tíme.
Krátke zhrnutie
Release notes nemajú predávať produkt.
Majú vysvetliť zmenu.
Dobré release notes:
- pomenúvajú konkrétnu zmenu,
- opisujú dopad,
- upozorňujú na riziká,
- pomáhajú supportu,
- pomáhajú testerom,
- znižujú chaos po release.
Ak sa release notes čítajú ako reklamný banner, tím pravdepodobne nepíše dokumentáciu pre prevádzku systému, ale pre marketing.