Séria: Ako písať dokumentáciu a manuály v IT projekte
V mnohých firmách existuje dokumentácia len na papieri.
Formálne je potrebná, ale v praxi ju nikto nepíše.
Keď sa otvorí téma dokumentácie, reakcie bývajú podobné:
„Nemáme na to čas.“
„Najprv treba dokončiť funkcionalitu.“
„To dopíšeme neskôr.“
„Veď to máme v kóde.“
Výsledok je predvídateľný.
Používateľská dokumentácia vzniká až vtedy, keď zákazník začne urgovať.
Administrátorská je zastaraná niekoľko rokov.
Technická dokumentácia neexistuje.
Support sa pýta vývojárov.
Nový kolega sa orientuje podľa rozhovorov na chodbe.
Problém nie je len v tom, že dokumentácia chýba.
Problém je, že tím nevidí jej hodnotu.
Prečo tímy dokumentáciu ignorujú
Vo väčšine projektov má dokumentácia zlú reputáciu.
Vníma sa ako:
- administratívna práca navyše
- povinnosť pre audit
- niečo, čo sa aj tak nečíta
Ak dokumentácia vzniká takto, je pochopiteľné, že ju tím odkladá.
Najčastejšia chyba je, že sa dokumentácia prezentuje ako ďalšia úloha navyše.
Skutočný problém: dokumentácia nie je súčasť systému
Ak dokumentácia stojí mimo projektu, vždy prehrá boj o čas.
Vývoj má deadline.
Testovanie má deadline.
Release má deadline.
Dokumentácia nie.
Preto sa odkladá.
Zmena prístupu: dokumentácia ako nástroj práce
Ak chceme tím presvedčiť, nestačí hovoriť o kvalite.
Treba ukázať, kde dokumentácia pomáha priamo v práci.
Najčastejšie v troch situáciách.
Onboarding nových kolegov
Bez dokumentácie sa nový človek pýta stále tie isté otázky.
Ako funguje tento modul?
Prečo sa to správa takto?
Je to bug alebo feature?
Ak existuje prehľadná dokumentácia, onboarding sa dramaticky skracuje.
Práca supportu
Ak support nemá dokumentáciu, každá druhá otázka končí eskaláciou na vývoj.
Vývojári potom riešia otázky, ktoré by support vedel vyriešiť sám.
Dobrá support dokumentácia dokáže výrazne znížiť počet eskalácií.
Orientácia v produkte
Po niekoľkých rokoch vývoja vznikne množstvo:
- klientských úprav
- historických rozhodnutí
- výnimiek v správaní systému
Bez dokumentácie prestáva byť jasné:
čo je Core funkcionalita
čo je klientská úprava
čo je historický workaround
Dokumentácia sa vtedy stáva mapou systému.
Najmenší krok, ktorý má zmysel
Ak tím dokumentáciu systematicky ignoruje, nie je realistické zaviesť veľký systém naraz.
Funguje skôr opačný prístup.
Začať s jednou jednoduchou vecou.
Napríklad:
- interná mapa funkcionalít
- krátka support dokumentácia k incidentom
- základný používateľský manuál
Keď tím uvidí praktický prínos, dokumentácia sa začne rozvíjať prirodzene.
Prečo je v tejto téme dôležitý tester
Tester často vidí najväčší rozdiel medzi tým:
ako systém funguje
a čo o ňom firma vie.
Pri testovaní sa objavujú otázky:
Kde je toto popísané?
Pre koho táto funkcionalita platí?
Od ktorej verzie existuje?
Tieto otázky veľmi prirodzene vedú k zlepšeniu dokumentácie.
Krátke zhrnutie
Tím sa nedá presvedčiť o dokumentácii argumentom „treba ju“.
Tím sa presvedčí až vtedy, keď uvidí, že dokumentácia:
- šetrí čas
- znižuje počet otázok
- pomáha orientovať sa v systéme
Vtedy prestane byť administratívnou povinnosťou.
Stane sa nástrojom práce.