Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Release vyšiel večer.
Ráno začali prichádzať incidenty.
- Integrácia prestala fungovať.
- Import odmietal staré dáta.
- Používatelia sa nevedeli prihlásiť.
- Support nevedel, čo sa deje.
Vývoj pritom tvrdil:
„Veď to bolo v release notes.“
A v release notes bola jedna veta:
- „Aktualizované API.“
- „Optimalizovaná validácia.“
- „Zlepšené bezpečnostné mechanizmy.“
Lenže nikto nepovedal, že:
- staré endpointy už nefungujú,
- pribudlo nové povinné pole,
- zmenila sa autentifikácia,
- starý formát dát už systém neakceptuje,
- a hlavne:
- čo je po novom správny spôsob použitia systému.
To už nie je bežná zmena.
To je breaking change.
Čo sa tu vlastne pokazilo (analýza systému)
Mnohé tímy nerozlišujú medzi:
- bežnou zmenou,
- a zmenou, ktorá mení správanie systému smerom navonok.
Breaking change znamená:
Po aktualizácii môže prestať fungovať niečo, čo predtým fungovalo.
To môže byť:
- API,
- export,
- import,
- autentifikácia,
- workflow,
- databázová štruktúra,
- konfigurácia,
- oprávnenia,
- integrácia.
Problém je, že tímy často komunikujú breaking changes príliš neurčito.
Alebo ešte horšie:
nekomunikujú ich vôbec.
Typická veta:
- „Zlepšené zabezpečenie.“
Reálny dopad:
- staré tokeny prestali fungovať,
- klient musí zmeniť konfiguráciu,
- integrácia sa musí prerobiť.
A často chýba ešte jedna kritická informácia:
- čo je nový podporovaný spôsob.
To nie je detail.
To je prevádzkové riziko.
Skutočné náklady (čas, chaos, riziko)
Zle komunikované breaking changes spôsobujú:
- incidenty po release,
- nefunkčné integrácie,
- výpadky prevádzky,
- paniku na supporte,
- konflikty s klientom,
- zbytočné bug reporty,
- rollbacky.
Najhoršie je, že veľká časť týchto problémov nevzniká samotnou zmenou.
Vzniká tým, že:
ľudia o zmene nevedeli alebo nerozumeli jej dopadu.
Typický problém vo firmách:
Vývoj považuje zmenu za „technický detail“.
Ale support, tester alebo klient ju vníma ako kritický zásah do systému.
Minimálny model riešenia
Každá breaking change by mala obsahovať minimálne:
- čo sa zmenilo,
- koho sa zmena týka,
- čo prestane fungovať,
- čo je po novom podporované,
- odkedy zmena platí,
- čo treba upraviť,
- či existuje prechodné obdobie,
- či existuje workaround.
Zlá formulácia:
- „Aktualizované API.“
Použiteľná formulácia:
- „Endpoint /orders/create od verzie 4.2 vyžaduje povinný parameter currency. Volania bez parametra budú odmietnuté HTTP 400.“
Zlá formulácia:
- „Zvýšené bezpečnostné štandardy.“
Použiteľná formulácia:
- „Od verzie 5.0 systém nepodporuje TLS 1.0 a TLS 1.1. Podporované sú TLS 1.2 a TLS 1.3.“
Ešte lepšia formulácia:
- „Od verzie 5.0 systém nepodporuje TLS 1.0 a TLS 1.1. Integrácie je potrebné aktualizovať na TLS 1.2 alebo TLS 1.3.“
To sú informácie, podľa ktorých:
- admin vie pripraviť upgrade,
- tester vie pripraviť retest,
- support vie reagovať na incident,
- klient vie upraviť integráciu.
Praktické pravidlo
Breaking change nemá len povedať:
- čo už nefunguje.
Má vysvetliť:
- čo funguje po novom,
- a čo treba zmeniť.
Ak používateľ po release zistí breaking change skôr než z release notes, komunikácia zlyhala.
Prepojenie na kvalitu a workflow
Breaking changes nemajú vzniknúť až pri písaní release notes.
Mali by byť označené už:
- v user story,
- v špecifikácii,
- v taskoch,
- v API dokumentácii,
- v Definition of Done.
Tím by mal vedieť:
- ktoré zmeny sú rizikové,
- ktoré vyžadujú migráciu,
- ktoré vyžadujú komunikáciu klientovi,
- ktoré vyžadujú prechodné obdobie.
Veľa firiem rieši breaking changes až po incidente.
To už je neskoro.
Dobrý proces robí opak:
identifikuje rizikové zmeny ešte pred release.
Krátke zhrnutie
Breaking change nie je technický detail.
Je to zmena, ktorá môže zastaviť prevádzku, integráciu alebo workflow používateľa.
Dobrá komunikácia breaking changes:
- znižuje chaos po release,
- chráni support,
- pomáha testerom,
- znižuje počet incidentov,
- znižuje závislosť na senioroch.
A hlavne:
neopisuje len starý svet, ktorý prestal fungovať.
Opisuje aj nový spôsob práce so systémom.
Ak release notes obsahujú len vetu:
- „vylepšenia a opravy“,
firma pravdepodobne nekomunikuje zmeny, ale skrýva ich.