Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
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.
Každý pracuje s inou verziou reality.
Čo sa pokazilo
Chýba prepojenie medzi jednotlivými krokmi:
- user story (čo chceme)
- špecifikácia (ako to funguje)
- test case (ako to overíme)
- manuál (ako to používateľ pochopí)
- release notes (ako to komunikujeme)
Vznikajú oddelene.
Bez väzby.
Jedna systémová myšlienka
Dokumentácia a testovanie nie sú samostatné aktivity.
Sú to prepojené vrstvy jedného reťazca.
Tento reťazec vyzerá takto:
User Story → Špecifikácia → Test Case → Manuál → Release notes
Každý krok nadväzuje na predchádzajúci.
Ak sa reťazec preruší, vzniká chaos.
Ako to má fungovať v praxi
1. User Story
Definuje hodnotu:
- čo má používateľ vedieť urobiť
- za akých podmienok
- s akým výsledkom
👉 základ pre všetko ostatné
2. Špecifikácia
Rozpisuje správanie:
- scenáre
- výnimky
- obmedzenia
- Core vs Custom
👉 musí byť testovateľná
3. Test Case (Xray „Test“)
Overuje správanie:
- konkrétne kroky
- dáta
- očakávaný výsledok
👉 vzniká zo špecifikácie
4. Manuál
Vysvetľuje správanie:
- ako funkcionalitu použiť
- čo sa stane v rôznych situáciách
👉 vychádza zo špecifikácie a overenej reality
5. Release notes
Komunikujú zmenu:
- čo pribudlo
- čo sa zmenilo
- čo sa zrušilo
👉 vychádzajú z reálne implementovanej funkcionality
Minimálny model prepojenia (Jira)
- User Story
- → Špecifikácia
- → Test (Xray = test case)
- → Release notes
- Špecifikácia
- → technické úlohy
- → test cases
- → dokumentácia
👉 všetko je prepojené, nie oddelené
Kedy je funkcionalita „hotová“
Nie keď:
- je naprogramovaná
- je otestovaná
Ale keď:
- existuje špecifikácia
- existujú test cases
- testy prešli
- manuál je hotový
- release notes sú pripravené
👉 inak je produkt neúplný
Krátke zhrnutie
User story, špecifikácia, test case, manuál a release notes
nie sú samostatné výstupy.
Sú to rôzne pohľady na tú istú funkcionalitu.
Ak nie sú prepojené, každý vidí niečo iné.
Ak prepojené sú, tím pracuje s jednou verziou reality.