Séria: Ako písať dokumentáciu a manuály v IT projekte
V predchádzajúcich článkoch sme pomenovali dva problémy:
- vo firmách často neexistuje dokumentácia,
- alebo existuje, ale mieša rôzne typy informácií.
Najčastejšie sa miešajú tieto veci:
- štandardné funkcionality produktu
- klientské úpravy
- interné poznámky tímu
- historické výnimky
Výsledok je jeden veľký dokument, ktorý síce existuje, ale nikto sa v ňom nevie orientovať.
V praxi sa osvedčuje rozdeliť dokumentáciu do viacerých vrstiev.
Dve základné kategórie dokumentácie
Najprv je dôležité urobiť jeden zásadný rozdiel.
Existujú dva typy dokumentácie:
- Oficiálna dokumentácia pre zákazníka
Je určená pre:
- klientov
- používateľov systému
- školenia
- verejnú dokumentáciu produktu
Môže existovať napríklad ako:
- dokument .doc alebo .pdf
- verejný web manuálu
- HTML dokumentácia produktu
Táto dokumentácia musí byť čistá a jednoduchá.
Opisuje iba štandardný produkt.
- Interná dokumentácia tímu
Používajú ju:
- tester
- support
- analytik
- developer
- školiteľ
Obsahuje:
- Core funkcionality
- klientské úpravy
- interné poznámky
- historický kontext
- informácie o verziách systému
Pre túto dokumentáciu sa veľmi dobre hodí HTML forma, pretože umožňuje prepojenie jednotlivých častí pomocou odkazov.
Praktický model: štyri vrstvy dokumentácie
Ak chceme oddeliť Core a Custom funkcionality a zároveň udržať prehľad v systéme, dá sa použiť model štyroch vrstiev.
- Core dokumentácia produktu
Toto je oficiálny manuál produktu.
Je určený pre zákazníkov.
Obsahuje:
- štandardné funkcionality
- štandardné workflow
- oficiálne podporované scenáre
Neobsahuje:
- klientské úpravy
- interné workaroundy
- historické výnimky
Tento dokument môže byť napríklad:
- PDF manuál
- dokument vo Worde
- webová HTML dokumentácia produktu
Je to opis produktu tak, ako je dostupný pre všetkých zákazníkov.
- Custom dokumentácia pre konkrétneho klienta
Ak má klient špecifické úpravy systému, vzniká dokumentácia pre daného zákazníka.
Obsahuje:
- Core funkcionalitu
- klientské úpravy
- špecifické workflow
- integrácie
- špeciálne pravidlá
Zákazník tak vidí presne:
- čo je štandardná funkcionalita
- a čo je jeho špecifické riešenie.
- Interná mapa funkcionalít
Táto vrstva je určená len pre tím.
Jej cieľ je jednoduchý:
odpovedať na otázku
„Máme túto funkcionalitu v produkte a pre koho?“
Veľmi dobre funguje jednoduchá tabuľka.
| Funkcionalita | Core | Klient A | Klient B | Verzia | Poznámka |
| Export XML | nie | áno | nie | 3.4 | klientská úprava |
| Schvaľovanie | áno | upravené | áno | 2.1 | extra krok u klienta A |
Túto mapu používajú:
- tester
- support
- analytik
- nový developer
Je to vlastne mapa reality systému.
- Interný používateľský manuál
Táto vrstva obsahuje najkompletnejší opis systému.
Obsahuje:
- Core funkcionality
- všetky klientské úpravy
- interné poznámky
- praktické scenáre
- odkazy na súvisiace časti systému
Je určená pre interný tím.
Používajú ju napríklad:
- tester pri testovaní
- support pri riešení incidentov
- školiteľ pri onboardingu
- analytik pri analýze systému
V tejto vrstve sa prirodzene prepájajú všetky informácie.
Prečo je interná dokumentácia vhodná ako HTML
Interná dokumentácia je veľmi prepojená.
Jedna funkcionalita môže mať:
- Core správanie
- klientské rozšírenia
- rôzne verzie
- závislosti na iných moduloch
Preto je HTML forma veľmi praktická.
Umožňuje:
- odkazy medzi funkciami
- prepojenie Core a Custom vrstiev
- jednoduchú navigáciu
- rýchlu aktualizáciu dokumentácie
Dokumentácia potom nie je lineárny text, ale sieť informácií.
Prečo je dôležité uvádzať verziu systému
Interná dokumentácia by mala obsahovať informáciu:
ku ktorej verzii systému sa funkcionalita viaže.
Bez toho vznikajú typické problémy:
- dokumentácia opisuje starú verziu systému
- tester nevie, či je správanie bug alebo zmena
- support nevie, čo platí pre konkrétnu inštaláciu
Jednoduchý stĺpec „verzia“ dokáže vyriešiť veľa nedorozumení.
Krátke zhrnutie
V praxi sa osvedčuje rozdeliť dokumentáciu na vrstvy:
- Core dokumentácia produktu
- Custom dokumentácia klienta
- Interná mapa funkcionalít
- Interný používateľský manuál
Oficiálna dokumentácia pre zákazníka má byť čistá a jednoduchá.
Interná dokumentácia má byť prepojený systém informácií, ktorý pomáha testerom, supportu aj vývoju orientovať sa v reálnom správaní produktu.
Vtedy dokumentácia prestane byť len textom.
Stane sa mapou produktu.