Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Admin klienta napísal:
„Pracovníčka omylom zmazala záznam. Dá sa obnoviť?“
Na prvý pohľad jednoduchá otázka.
V testovacom prostredí som zmazala záznam.
V databáze som ho našla.
Lenže:
nevedela som, ako ho obnoviť.
Nakoniec mi vývojár povedal:
Stačí zmeniť hodnotu v stĺpci OMYL z 0 na 1.
Záznam sa znovu objavil.
Bez tejto informácie by som na to neprišla.
Stĺpec sa volal OMYL.
Iné stĺpce mali názvy C1, C2, C3.
Adresár nebol v tabuľke ADRESAR, ale v KLIENTI.
Dáta existovali.
Len im nikto nerozumel.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je v databáze.
Problém je, že dátový model nie je zrozumiteľný.
V tomto príklade sa stretlo viac chýb naraz:
- názvy stĺpcov neodrážajú význam
- nie je jasné, čo pole robí
- chýba dokumentácia soft delete
- názvy tabuliek nezodpovedajú doméne
- význam dát je v hlave vývojára
Z pohľadu systému ide o bežnú vec:
záznam sa nemaže, len sa označí
Lenže z pohľadu tímu:
to vyzerá ako „záhada v databáze“
Dátový model tu neplní svoju základnú funkciu:
vysvetliť, ako systém pracuje s dátami.
Skutočné náklady (čas, chaos, riziko)
Takýto stav má veľmi konkrétne dopady:
- support nevie odpovedať na jednoduchú otázku
- tester nevie overiť správanie systému
- admin nevie opraviť chybu bez vývojára
- vzniká závislosť na konkrétnom človeku
Typická situácia:
funkcionalita existuje
ale nie je použiteľná bez interného know-how
A to je problém kvality.
Minimálny model riešenia
Nie je cieľ prepisovať databázu.
Cieľ je spraviť ju čitateľnou.
1. Zmysluplné názvy
- tabuľky majú odrážať doménu (napr. ADRESAR, nie KLIENTI, ak ide o adresár)
- stĺpce majú popisovať význam (napr. DELETED_FLAG, nie OMYL)
2. Popis významu polí
Pri každom dôležitom poli má byť jasné:
- čo znamená
- aké hodnoty nadobúda
- čo tieto hodnoty spôsobujú
Príklad:
OMYL = 0 → záznam skrytý
OMYL = 1 → záznam aktívny
Bez tohto je pole nepoužiteľné.
3. Dokumentácia soft delete
Ak systém používa soft delete, musí to byť explicitne uvedené:
- ktoré tabuľky ho používajú
- ktoré pole to riadi
- ako sa záznam obnovuje
- či existuje hard delete
Toto je častý zdroj nedorozumení.
4. Prepojenie na funkcionalitu
Dátový model nemá byť izolovaný.
Musí byť jasné:
- ktorá funkcionalita pracuje s ktorou tabuľkou
- ktoré polia ovplyvňujú správanie systému
- ktoré zmeny sú bezpečné a ktoré nie
Príklad
Bez dokumentácie:
záznam sa „nejako zmaže“
S dokumentáciou:
- záznam sa nemaže
- nastaví sa príznak deleted_flag = 0
- systém ho prestane zobrazovať
- obnovenie = zmena hodnoty na 1
Zrazu je jasné:
čo sa stalo
ako to opraviť
čo testovať
Mini checklist
Majú tabuľky zmysluplné názvy?
Majú stĺpce jasný význam?
Je popísané, čo robia kľúčové polia?
Je zdokumentovaný soft delete?
Je jasné, kde sa nachádzajú konkrétne dáta (napr. adresár)?
Ak nie, databáza síce funguje, ale nie je pochopená.
Prepojenie na kvalitu a workflow
Toto je presne moment, kde sa láme kvalita.
Bez dátovej dokumentácie:
- tester testuje naslepo
- support háda riešenie
- admin je odkázaný na vývojára
S dátovou dokumentáciou:
- vieš rýchlo nájsť príčinu
- vieš opraviť stav
- vieš vysvetliť správanie systému
A hlavne:
znalosť sa presunie z hlavy do systému.
Krátke zhrnutie
Dátový model nie je len o tabuľkách.
Je o tom, či:
- názvy dávajú zmysel
- polia majú jasný význam
- správanie systému je pochopiteľné
Ak nie:
dáta existujú
ale tím im nerozumie
Ak áno:
systém je čitateľný
a dá sa podľa neho pracovať
A presne o tom je technická dokumentácia.