Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Tester otvorí špecifikáciu.
„Používateľ môže upraviť objednávku.“
Bez ďalších detailov.
Tester sa pýta:
- Kedy ju môže upraviť?
- Ktoré polia?
- Čo ak je už zaplatená?
- Čo ak ide o klientskú výnimku?
Odpovede:
- „To je jasné.“
- „To robí systém.“
- „To sa dohodlo.“
A tím začne dopĺňať realitu počas vývoja.
Čo sa tu vlastne pokazilo (analýza systému)
Špecifikácia neplní svoju funkciu.
Nie je:
- jednoznačná
- testovateľná
- kompletná
Vzniká dokument, ktorý:
- každý interpretuje inak
- neobsahuje výnimky
- nerieši hranice systému
- mieša Core a Custom
Výsledok:
Špecifikácia nie je zdroj pravdy.
Je to len orientačný text.
Skutočné náklady (čas, chaos, riziko)
- tester nevie pripraviť test cases
- vznikajú falošné bugy
- vývoj implementuje inú logiku
- manuál opisuje inú verziu reality
- support improvizuje
- tím je závislý na senioroch
Najväčší problém:
Rozhodnutia sa robia počas vývoja, nie v špecifikácii.
Minimálny model riešenia
Špecifikácia musí byť:
- jednoznačná
- testovateľná
- kompletná v rámci rozsahu
To znamená:
- definované vstupy
- definované výstupy
- definované chybové stavy
- definované obmedzenia
- jasné oddelenie Core vs Custom
Ak z nej nevieš napísať test case bez otázok, nie je hotová.
Praktické ukážky
- Nejednoznačná formulácia
Zle:
Používateľ môže upraviť objednávku.
Dopad:
Každý si to vysvetlí inak.
Lepšie:
Používateľ môže upraviť objednávku do momentu jej zaplatenia. Po zaplatení je úprava zakázaná.
- Chýbajúce výnimky
Zle:
Systém odošle notifikáciu.
Dopad:
Čo ak email neexistuje? Čo ak je služba nedostupná?
Lepšie:
Systém odošle notifikáciu.
Ak odoslanie zlyhá, zobrazí sa chyba a akcia sa neuloží.
- Miešanie riešenia s požiadavkou
Zle:
Použiť tabuľku orders_archive na uloženie dát.
Dopad:
Špecifikácia diktuje technické riešenie.
Lepšie:
Objednávky staršie ako 30 dní sa archivujú a nie sú dostupné v štandardnom zobrazení.
- Nejasné hranice systému
Zle:
Systém spracuje platbu.
Dopad:
Nie je jasné, čo robí náš systém a čo externá služba.
Lepšie:
Systém odošle požiadavku na platobnú bránu a spracuje odpoveď. Samotné spracovanie platby vykonáva externá služba.
- Core vs Custom nie je rozlíšené
Zle:
Systém umožňuje export do XML.
Dopad:
Tester nevie, či to má byť všade.
Lepšie:
Export do XML je dostupný len pre klienta XY.
- Chýbajúce obmedzenia
Zle:
Používateľ môže nahrať súbor.
Dopad:
Aký typ? Aká veľkosť?
Lepšie:
Používateľ môže nahrať súbor typu PDF do veľkosti 10 MB.
Prepojenie na kvalitu a workflow
Špecifikácia je začiatok celého reťazca:
User Story → Špecifikácia → Test → Dokumentácia → Release
Ak je chybná:
- testovanie sa mení na hádanie
- dokumentácia sa nedá napísať
- support nemá z čoho vychádzať
Problém sa prenáša ďalej.
Krátke zhrnutie
Najčastejšie chyby v špecifikáciách:
- nejednoznačnosť
- chýbajúce výnimky
- miešanie riešenia s požiadavkou
- nejasné hranice systému
- chýbajúce Core vs Custom
- chýbajúce obmedzenia
Špecifikácia nie je poznámka.
Je to základ, na ktorom stojí testovanie, dokumentácia aj celý projekt.