Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
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ť.
Začnú sa otázky:
- Čo sa má stať pri chybovom stave?
- Aké sú hraničné podmienky?
- Je toto core funkcionalita alebo klientská úprava?
- Je to bug alebo plánované správanie?
A dokumentácia sa potom nepíše podľa špecifikácie.
Píše sa podľa toho, čo už existuje v systéme.
Lenže v tom momente už riešime dôsledky, nie príčinu.
Čo sa tu vlastne pokazilo (analýza systému)
Pri písaní dokumentácie si často uvedomím jednu vec:
problém nevznikol pri manuáli.
Vznikol oveľa skôr.
Pri špecifikácii.
Špecifikácia je v skutočnosti prvá dokumentácia systému.
Je to prvé miesto, kde sa má presne definovať:
- čo systém robí
- čo nerobí
- aké má vstupy
- aké má výstupy
- aké sú obmedzenia
- čo sa deje pri chybách
Ak tieto informácie neexistujú, všetky ďalšie dokumenty budú len pokus vysvetliť niečo, čo nikdy nebolo jasne popísané.
Špecifikácia je základ pre:
- implementáciu
- testovanie
- používateľské manuály
- administrátorskú dokumentáciu
- support manuály
- release notes
Ak je základ nejasný, chaos sa prenáša ďalej.
Skutočné náklady (čas, chaos, riziko)
Nejasná špecifikácia sa v projekte prejaví veľmi konkrétne.
Najskôr to vyzerá nenápadne – pár otázok navyše.
Postupne sa však začnú objavovať typické problémy.
Tester nevie napísať testy
Bez jasného správania systému vznikajú:
- neúplné test cases
- rôzne interpretácie funkcionality
- veľa doplňujúcich otázok na analytika
Vývoj implementuje „svoj výklad zadania“
Vývojár môže vyriešiť problém technicky správne, ale úplne inak, než si predstavoval biznis.
Dokumentácia opisuje realitu, nie zadanie
Používateľský manuál potom vysvetľuje:
„Takto systém funguje.“
Nie:
„Takto fungovať má.“
Support nevie rozhodnúť, či ide o bug
Ak nie je jasné očakávané správanie, každá chyba vyvoláva diskusiu:
Je to bug?
Alebo feature?
Minimálny model riešenia
Dobrá špecifikácia nemusí byť rozsiahly dokument.
Musí však obsahovať základné informácie, z ktorých sa dá pochopiť správanie systému.
Keď čítam špecifikáciu, hľadám najmä tieto veci:
| Oblasť | Otázka |
| Funkcionalita | Čo systém robí |
| Vstupy | Aké údaje systém prijíma |
| Výstupy | Čo systém vracia alebo zobrazí |
| Chybové stavy | Čo sa stane pri chybe |
| Obmedzenia | Čo systém nepodporuje |
| Rozsah | Platí to pre všetkých alebo len pre konkrétneho klienta |
Ak špecifikácia obsahuje tieto informácie, tester dokáže napísať test cases bez ďalších otázok.
To je veľmi dobrý signál kvality.
Prepojenie na kvalitu a workflow
Pri práci v projekte sa veľmi rýchlo ukáže, že špecifikácia je začiatok celého reťazca.
Typický tok práce vyzerá približne takto:
Špecifikácia → Implementácia → Testovanie → Dokumentácia → Release → Support
Ak je problém na začiatku, prenesie sa do každej ďalšej fázy.
Ako testerka často vidím, že najlacnejšie chyby sa dajú odhaliť práve pri čítaní špecifikácie.
Pri dobre napísanej špecifikácii je možné hneď identifikovať:
- chýbajúce scenáre
- nejasné formulácie
- konflikty medzi požiadavkami
- chýbajúce chybové stavy
Testovanie špecifikácie je často najjednoduchší spôsob, ako predísť budúcim problémom.
Krátke zhrnutie
Špecifikácia nie je len zadanie pre vývoj.
Je to prvá dokumentácia systému.
Ak je nejasná:
- vývoj implementuje rôzne interpretácie
- tester nevie napísať presné testy
- dokumentácia opisuje náhodnú realitu
- support rieši zbytočné incidenty
Dobrá dokumentácia sa nezačína pri manuáli.
Začína pri špecifikácii.