Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Funkcionalita je implementovaná.
Existuje:
- user story
- špecifikácia
- testy
Ale administrátorská príručka chýba alebo je neúplná.
Admin potom:
- nevie, ako funkciu nastaviť
- nevie, čo musí byť splnené, aby fungovala
- nevie, čo skontrolovať, keď nefunguje
Výsledok:
Funkcionalita existuje.
Ale v praxi sa nepoužíva alebo zlyháva.
Čo sa tu vlastne pokazilo (analýza systému)
Chýba prepojenie medzi:
- špecifikáciou
- testovaním
- administrátorskou dokumentáciou
Každý artefakt opisuje tú istú vec.
Ale iným jazykom a bez prepojenia.
Tento problém je viditeľný aj pri používateľských manuáloch.
Skutočné náklady (čas, chaos, riziko)
- admin robí nesprávnu konfiguráciu
- support rieši opakované otázky
- tester nevie overiť reálnu prevádzku
- onboarding trvá dlhšie
Funkcionalita nie je „dokončená“, aj keď je nasadená.
Minimálny model riešenia
Administrátorská príručka musí vzniknúť z rovnakého zdroja ako:
- user story
- špecifikácia
- testy
Nie dodatočne.
Praktická ukážka
1. User story
Názov: Export faktúr do XML
Ako účtovník
chcem exportovať faktúry do XML
aby som ich mohol použiť v účtovnom systéme
2. Špecifikácia požiadavky
Popis funkcionality:
Systém umožňuje export faktúr do XML na základe zadaného rozsahu dátumov.
Vstupy:
- dátum od
- dátum do
- typ faktúr (voliteľné)
Správanie systému:
- filtruje faktúry podľa vstupov
- exportuje len schválené faktúry
- generuje XML súbor
- súbor sa stiahne
Obmedzenia:
- export obsahuje len schválené faktúry
Chybové stavy:
- neplatný rozsah dátumov
- žiadne dáta na export
3. Akceptačné kritériá
- používateľ zadá dátumový rozsah
- systém exportuje len faktúry v rozsahu
- export obsahuje len schválené faktúry
- výstup je XML súbor
- súbor sa stiahne
- pri chybe sa zobrazí hlásenie
4. Testovacie prípady (výber)
- export s platným rozsahom
- export bez dát
- export s neplatným rozsahom
- kontrola formátu XML
- kontrola stiahnutia
5. Administrátorská príručka
Názov oblasti
Export faktúr do XML
Kedy funkciu použiť
Používa sa na export faktúr do externého účtovného systému.
Požiadavky na konfiguráciu
- systém musí mať nastavený exportný modul
- používateľ musí mať oprávnenie na export
- databáza musí obsahovať schválené faktúry
Postup nastavenia
- over, že exportný modul je aktívny
- nastav oprávnenia pre rolu
- skontroluj prístup k úložisku súborov
Dopady nastavení
- bez oprávnenia nie je možné export spustiť
- nesprávna konfigurácia môže zabrániť stiahnutiu súboru
Diagnostika problémov
- skontroluj logy exportu
- over rozsah dátumov
- over existenciu schválených faktúr
Typické chyby
- neexistujú dáta na export
- nesprávny dátumový rozsah
- chýbajú oprávnenia
Prepojenie na používateľa
Používateľ vykoná export cez UI.
Admin zabezpečuje, že funkcia funguje.
Prepojenie na kvalitu a workflow
Toto je jeden reťazec:
User story → Špecifikácia → Testy → Dokumentácia
Ak chýba jeden článok:
- funkcionalita nie je plnohodnotná
- tím stráca čas
- vznikajú chyby
Dokumentácia nie je posledný krok.
Je súčasť Definition of Done.
Krátke zhrnutie
Jedna funkcionalita má viac pohľadov:
- user story definuje cieľ
- špecifikácia správanie
- testy overenie
- admin dokumentácia prevádzku
Ak tieto pohľady nie sú prepojené, systém nefunguje ako celok.
Ak sú prepojené, každý v tíme vie, čo má robiť.