Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Firma má interné manuály.
Support ich otvorí.
Ale:
- nenájde odpoveď
- alebo nájde niečo neaktuálne
- alebo nevie, či je to správne
A ide sa pýtať kolegu.
Dokumentácia existuje.
Ale nepoužíva sa.
Čo sa tu vlastne pokazilo (analýza systému)
Chyba nie je jedna.
Je to kombinácia opakujúcich sa problémov:
- zlý spôsob písania
- chýbajúca štruktúra
- neexistujúci proces
Výsledok:
- dokumentácia nie je nástroj
- je to archív textov
Skutočné náklady (čas, chaos, riziko)
Tieto chyby majú reálny dopad:
- pomalý support
- zbytočné eskalácie
- závislosť na senioroch
- nekonzistentné odpovede
A hlavne:
firma investuje čas do niečoho, čo neprináša hodnotu.
Minimálny model riešenia
Pozrime sa na najčastejšie chyby priamo na príkladoch.
Chyba 1: Funkčný opis namiesto riešenia problému
Zápis:
„Modul Export umožňuje export dát do XML…“
Problém:
- nepomáha vyriešiť incident
Správne:
„Export sa nespustí“
- príčiny
- diagnostika
- riešenie
Chyba 2: Chýbajúca diagnostika
Zápis:
„Skontrolujte nastavenia.“
Problém:
- support nevie čo
- support háda
Správne:
- kde kliknúť
- čo overiť
- aká hodnota má byť
Chyba 3: Workaround bez označenia
Zápis:
„Rozdeľte export na menšie časti.“
Problém:
- vyzerá ako finálne riešenie
- prežije dlhšie než bug
Správne:
- označiť ako workaround
- prepojiť na bug
- uviesť obmedzenia
Chyba 4: Zmiešané Core a Custom
Zápis:
popis správania bez kontextu
Problém:
- support nevie, pre koho to platí
- vznikajú falošné bugy
Správne:
- „platí pre všetkých“
- „platí pre klienta XY“
Chyba 5: Nekonzistentné názvy
Zápisy:
- „problém s loginom“
- „user sa nevie prihlásiť“
- „chyba autentifikácie“
Problém:
- nedá sa vyhľadávať
Správne:
- jeden štandard názvov
- jazyk používateľa
Chyba 6: Neaktuálne riešenia
Zápis:
postup, ktorý už neplatí
Problém:
- support robí chyby
- stráca dôveru
Správne:
- verziovanie
- označenie zastaraných riešení
- archivácia
Chyba 7: Chýbajúce prepojenia
Zápis:
izolovaný článok
Problém:
- support nenájde súvisiace riešenia
Správne:
- prepojenie na bug
- prepojenie na podobné problémy
Prepojenie na kvalitu a workflow
Tieto chyby nevznikajú náhodne.
Vznikajú, keď:
- dokumentácia nie je súčasť workflow
- neexistuje šablóna
- nikto ju neudržiava
Riešenie:
- zaviesť proces
- zaviesť štruktúru
- zaviesť kontrolu
Krátke zhrnutie
Interné manuály zlyhávajú nie preto, že neexistujú.
Zlyhávajú preto, že:
- nie sú použiteľné
- nie sú aktuálne
- nie sú konzistentné
Najčastejšie chyby:
- funkčný opis namiesto symptómu
- chýbajúca diagnostika
- neoznačené workaroundy
- zmiešané Core a Custom
- nekonzistentné názvy
- zastarané riešenia
Ak sa podľa dokumentácie nedá vyriešiť problém bez otázky na kolegu,
dokumentácia zlyháva.