Séria: Ako písať dokumentáciu a manuály v IT projekte
V mnohých firmách vyzerá realita približne takto:
- vývoj implementuje novú funkcionalitu
- tester ju otestuje
- verzia ide do produkcie
Dokumentácia?
Používateľská sa dopíše o niekoľko verzií neskôr, keď zákazník začne urgovať.
Administrátorská je často stará niekoľko rokov.
Technická dokumentácia nevzniká vôbec.
Support si pomáha improvizáciou.
Dokumentácia pre AI zatiaľ neexistuje.
Problém nie je v tom, že tím nechce písať dokumentáciu.
Problém je, že dokumentácia nie je súčasť workflow projektu.
Ako to vyzerá v realite
Typický proces vo firmách vyzerá takto:
Feature → Implementácia → Test → Release
Dokumentácia stojí mimo tohto procesu.
Výsledok:
- dokumentácia zaostáva za systémom
- support nevie rýchlo reagovať
- onboarding nových kolegov je pomalý
- AI systémy nemajú kvalitný zdroj informácií
A tester sa často stáva jediným človekom, ktorý vidí, že realita systému a dokumentácia sa rozchádzajú.
Minimálny model workflow
Ak má dokumentácia fungovať, musí byť súčasťou procesu.
Jednoduchý model môže vyzerať takto:
Feature → Test → Dokumentácia → Release
Dôležitá vec je, že dokumentácia nevzniká až po release.
Vzniká pred ním.
Čo sa má stať pri každej novej funkcionalite
Keď vznikne nová feature alebo zmena správania systému, tím by mal urobiť krátku kontrolu dopadu.
Otázka nie je „treba písať dokumentáciu?“.
Otázka je:
Ktoré vrstvy dokumentácie sa touto zmenou dotknú?
Vrstvy dokumentácie, ktoré sa môžu meniť
Jedna funkcionalita môže zasiahnuť viac typov dokumentácie.
Používateľský manuál
Ak sa zmení správanie systému pre používateľa:
- nový postup
- nové tlačidlo
- nové pravidlo
je potrebné aktualizovať používateľský manuál.
Nie vždy ide o nový článok.
Niekedy stačí doplniť jeden krok alebo upozornenie.
Administrátorská dokumentácia
Zmena môže ovplyvniť napríklad:
- konfiguráciu systému
- oprávnenia
- systémové požiadavky
- integrácie
Ak sa zmení napríklad konfiguračný parameter alebo proces nasadenia, musí sa to objaviť v admin dokumentácii.
Support dokumentácia
Support potrebuje vedieť:
- aké chyby môže používateľ vidieť
- aké sú typické príčiny
- ako problém diagnostikovať
Ak sa zmení správanie systému, vznikajú nové scenáre incidentov.
Tie by mali byť zapísané do support dokumentácie.
Technická dokumentácia
Technická dokumentácia opisuje napríklad:
- architektúru systému
- API
- dátový model
- integrácie
Ak nová feature mení tieto časti systému, technická dokumentácia by mala byť aktualizovaná.
Práve táto vrstva však v mnohých firmách nevzniká vôbec.
Dokumentácia pre AI
Ak firma používa chatbot alebo RAG systém, dokumentácia musí byť:
- jednoznačná
- štruktúrovaná
- bez zmiešaných výnimiek
Nové funkcionality znamenajú nové odpovede v znalostnej báze.
Ak sa tieto informácie nedoplnia, AI začne odpovedať nepresne.
Jednoduchý kontrolný krok pred release
Pred nasadením novej verzie môže tím použiť jednoduchý checklist:
- Zasahuje zmena používateľský manuál?
- Zasahuje admin dokumentáciu?
- Vznikajú nové support scenáre?
- Mení sa technická architektúra alebo API?
- Treba doplniť informácie do AI znalostnej bázy?
Ak je odpoveď áno, dokumentácia sa upraví ešte pred release.
Prepojenie s Definition of Done
Veľa problémov vzniká preto, že dokumentácia nie je súčasťou definície hotovej práce.
Ak je feature implementovaná a otestovaná, ale dokumentácia neexistuje, z pohľadu systému nie je dokončená.
Jednoduché pravidlo môže znieť:
Feature je hotová až vtedy, keď je aktualizovaná dokumentácia.
Prečo je to dôležité pre testerov
Tester je často prvý človek, ktorý vidí dopad zmeny na systém.
Vidí:
- nové správanie
- nové chybové stavy
- nové scenáre používateľov
Preto môže tester veľmi prirodzene upozorniť na otázku:
„Kde sa táto zmena objaví v dokumentácii?“
Krátke zhrnutie
Dokumentácia nevzniká sama od seba.
Ak nie je súčasťou workflow projektu, vždy bude za systémom zaostávať.
Preto je užitočné zaradiť ju priamo do procesu:
Feature → Test → Dokumentácia → Release
A pri každej zmene systému si položiť jednoduchú otázku:
Ktoré vrstvy dokumentácie sa touto zmenou menia?
Vtedy dokumentácia prestane byť administratívnou povinnosťou.
Stane sa súčasťou kvality produktu.
Checklist: dopad novej funkcionality na dokumentáciu
Pred release novej funkcionality alebo zmeny správania systému si tím môže prejsť jednoduchý kontrolný zoznam.
- Používateľská dokumentácia
- Mení sa workflow používateľa?
- Pribudlo nové tlačidlo, formulár alebo krok?
- Zmenili sa validačné pravidlá alebo chybové hlášky?
Ak áno, je potrebné aktualizovať používateľský manuál.
- Administrátorská dokumentácia
- Mení sa konfigurácia systému?
- Pribudol nový parameter alebo nastavenie?
- Menia sa oprávnenia alebo roly?
- Menia sa systémové požiadavky?
Ak áno, treba aktualizovať admin dokumentáciu.
- Support dokumentácia
- Môžu sa objaviť nové chybové hlášky?
- Mení sa diagnostika problému?
- Existujú nové typické incidenty?
Ak áno, treba doplniť support manuál.
- Technická dokumentácia
- Mení sa API?
- Mení sa dátový model?
- Menia sa integračné body alebo architektúra?
Ak áno, treba aktualizovať technickú dokumentáciu.
- Interná mapa funkcionalít
- Je funkcia Core alebo Custom?
- Pre ktorých klientov platí?
- Od ktorej verzie systému existuje?
Tieto informácie by mali byť zapísané v internej mape funkcionalít.
- Dokumentácia pre AI
- Obsahuje nová funkcionalita informácie, na ktoré sa môže používateľ pýtať?
- Zmenili sa existujúce odpovede v znalostnej báze?
- Je potrebné pridať nové články alebo aktualizovať existujúce?
Ak áno, treba doplniť AI znalostnú bázu.
Mini pravidlo pre tím
Pred release by mal existovať jednoduchý kontrolný krok:
Ktoré vrstvy dokumentácie sa touto zmenou menia?
Ak sa táto otázka položí pri každej feature, dokumentácia začne držať krok so systémom.
A prestane sa dopisovať až vtedy, keď zákazník začne urgovať.