Ako a prečo písať rôzne druhy dokumentácie a príručiek (používateľská, správcovská, AI….)
Séria: Ako písať dokumentáciu a manuály v IT projekte
Manuál existoval. Mal 60 strán.
Používateľ zavolal support a pýtal sa:
„Kde nájdem export?“
Odpoveď bola na strane 42.
Lenže:
Používateľ ten manuál nečítal.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Tester otvorí špecifikáciu.
„Používateľ môže upraviť objednávku.“
Bez ďalších detailov.
Tester sa pýta:
Odpovede:
Séria: Ako písať dokumentáciu a manuály v IT projekte
Na projekte vznikne funkcionalita.
User story existuje.
Vývoj ju implementuje.
Tester ju otestuje.
A potom:
Používateľ nevie, že existuje.
Manuál ju opisuje inak.
Release notes ju spomenú neurčito.
Support nevie, ako sa správa.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Na projekte sa rieši nová funkcionalita.
User story je zapísaná.
Špecifikácia vznikne.
Vývoj implementuje.
Po čase sa tester pýta:
„Prečo to funguje len u klienta XY?“
„Je to bug alebo feature?“
„Platí to pre všetkých alebo len pre jedného zákazníka?“…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Na projekte sa objaví nová funkcionalita.
Analytik pripraví user story a krátku špecifikáciu.
Vývoj začne implementovať.
Tester pripraví test cases až keď je funkcionalita hotová.
A vtedy sa objavia otázky:
Séria: Ako písať dokumentáciu a manuály v IT projekte
Na projekte sa objaví nové zadanie.
User story má tri vety.
Akceptačné kritériá sú dve odrážky.
„Treba pridať export údajov.“
Vývojár sa opýta analytika, ako to má fungovať.
Tester sa opýta vývojára, čo vlastne implementoval.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
V projekte sa začne vyvíjať nová funkcionalita.
Analytik napíše krátky popis do úlohy v Jire.
Vývojár si ho vysvetlí jedným spôsobom.
Tester iným.
A zákazník očakáva ešte niečo tretie.
Keď príde čas písať dokumentáciu, objaví sa zvláštna situácia:
nikto vlastne presne nevie, ako má funkcionalita fungovať.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Najjednoduchší spôsob, ako zlepšiť kvalitu zadania, je porovnať slabé a dobré príklady.
Na prvý pohľad často vyzerajú podobne, ale rozdiel v zrozumiteľnosti pre tím je veľký.
Nižšie je niekoľko typických situácií z projektov.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
V projekte pribudne nová funkcionalita.
V Jire existuje Epic, niekoľko user story a pár taskov. Vývoj prebehne, tester pripraví testy a funkcionalita sa nasadí do produkcie.
Potom príde moment, keď treba pripraviť:
A tím začne hľadať, kde vlastne je napísané:
Časť informácií je v user story.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Nový tester v projekte otvorí user story a vidí funkcionalitu, ktorá sa zdá byť súčasťou produktu.
Otestuje ju, napíše test case a pripraví poznámky do dokumentácie.
O niekoľko dní sa dozvie, že:
„To je špeciálna úprava pre klienta XY.“…
Séria: Ako písať dokumentáciu a manuály v IT projekte
V Jire sa objaví user story s jedným akceptačným kritériom:
„Systém správne spracuje objednávku.“
Vývojár začne rozmýšľať, čo presne má implementovať.
Tester sa neskôr snaží zistiť, ako to vlastne funguje.
A keď niekto píše manuál, musí funkcionalitu najprv skúšať v systéme, aby zistil, čo robí.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
V mnohých projektoch sa stretávame s vetami typu:
Na prvý pohľad to vyzerá ako normálne požiadavky.
Problém je, že nie je jasné:
Séria: Ako písať dokumentáciu a manuály v IT projekte
V mnohých projektoch sú akceptačné kritériá napísané voľným textom.
Napríklad:
Používateľ môže exportovať zoznam objednávok do CSV.
Export je dostupný len pre oprávnených používateľov.
Pri prázdnom zozname sa zobrazí hláška.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
User story je často jedna veta. A akceptačné kritériá k nej buď nie sú vôbec, alebo sú tiež len „nejaké poznámky“.
Potom to dopadne vždy rovnako:
Séria: Ako písať dokumentáciu a manuály v IT projekte
Prečo sa v sérii o dokumentácii venujeme user story
Na prvý pohľad to môže vyzerať zvláštne.
Táto séria je o dokumentácii, manuáloch a znalostných bázach.
Prečo teda začíname pri user story?…
Séria: Ako písať dokumentáciu a manuály v IT projekte
V mnohých firmách existuje dokumentácia len na papieri.
Formálne je potrebná, ale v praxi ju nikto nepíše.
Keď sa otvorí téma dokumentácie, reakcie bývajú podobné:
„Nemáme na to čas.“
„Najprv treba dokončiť funkcionalitu.“
„To dopíšeme neskôr.“
„Veď to máme v kóde.“…
Séria: Ako písať dokumentáciu a manuály v IT projekte
V mnohých firmách vyzerá realita približne takto:
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.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
V predchádzajúcich článkoch sme pomenovali dva problémy:
Najčastejšie sa miešajú tieto veci:
Výsledok je jeden veľký dokument, ktorý síce existuje, ale nikto sa v ňom nevie orientovať.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
V predchádzajúcich článkoch sme si ukázali dve veci:
Teraz sa pozrime na problém, ktorý je menej viditeľný – ale v produktových firmách veľmi častý.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
V prvom článku série „Nie je manuál ako manuál“ som pomenovala problém miešania cieľových skupín v dokumentácii.
Dnes sa posunieme o krok ďalej.
Čo sa deje vo firmách, kde dokumentácia neexistuje vôbec?
Príde nový kolega.…
