Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Raz som riešila bug, ktorý na prvý pohľad vyzeral ako chyba aplikácie.
Správanie systému bolo nesprávne, ale nebolo jasné prečo.
Postupne som začala kontrolovať staršie verzie, krok po kroku späť, až som našla bod zlomu: pri jednej verzii to ešte fungovalo, pri novšej už nie.
Nakoniec sa ukázalo, že problém nebol vo funkcionalite.
Bol vo verzii programovacieho jazyka.
Teda nie bug v logike systému, ale nezdokumentovaná nekompatibilita prostredia.
To je presne situácia, keď tím rieši chybu na zlom mieste.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nebol len technický.
Bol dokumentačný.
Nebolo jasne uvedené:
- ktoré verzie programovacieho jazyka sú podporované
- od akej verzie vzniká problém
- čo je ešte podporované a čo už nie
- či ide o tvrdú systémovú požiadavku alebo len odporúčanie
Toto je typická chyba vo firmách:
systémové požiadavky síce existujú, ale nie sú zapísané tam, kde ich admin alebo tester naozaj nájde.
Sú:
- v starom e-maile
- v hlave vývojára
- v poznámke pri release
- alebo vôbec nikde
Výsledok je jednoduchý:
tím rieši „bug“, ktorý je v skutočnosti problém prostredia.
Skutočné náklady (čas, chaos, riziko)
Ak nie sú systémové požiadavky jasne uvedené, vznikajú veľmi konkrétne škody:
- tester stráca čas hľadaním chyby v aplikácii
- vývoj rieši problém, ktorý nespôsobil kód funkcionality
- support nevie odlíšiť bug od nekompatibility
- admin nasadí systém na nepodporované prostredie
- firma obviňuje aplikáciu za problém infraštruktúry alebo runtime prostredia
Najhoršie na tom je, že všetci môžu pracovať poctivo, ale na zlom probléme.
A to je drahé.
Minimálny model riešenia
Cieľ nie je vypísať technické údaje do tabuľky a odškrtnúť si dokumentáciu.
Cieľ je jasne definovať, v akom prostredí systém funguje a kde sú jeho hranice.
1. Oddeliť minimálne a odporúčané požiadavky
Admin musí hneď vidieť rozdiel medzi týmto:
| Typ požiadavky | Význam |
| Minimálne požiadavky | systém ešte funguje |
| Odporúčané požiadavky | systém funguje stabilne a s rezervou |
Bez tohto rozlíšenia vzniká falošný dojem, že všetky hodnoty sú rovnako kritické.
2. Uvádzať presné verzie, nie všeobecné formulácie
Nestačí napísať:
- podporovaný Linux
- podporovaná databáza
- podporovaný runtime
Treba uviesť presne:
- verziu operačného systému
- verziu databázy
- verziu programovacieho jazyka alebo runtime
- verziu web servera alebo iných závislostí
Práve pri verzii programovacieho jazyka môže vzniknúť problém, ktorý sa navonok tvári ako bug aplikácie.
3. Uviesť, čo je podporované a čo už nie
Toto je kľúčová časť, ktorá často chýba.
Dokumentácia nemá hovoriť len:
- čo podporujeme
ale aj:
- čo už nepodporujeme
- od ktorej verzie je zmena
- aké je riziko pri staršom alebo novšom prostredí
Príklad:
| Komponent | Podporované verzie | Nepodporované verzie | Poznámka |
| Programovací jazyk / runtime | 3.10 – 3.11 | 3.12+ | Od verzie 3.12 sa mení správanie knižnice X |
| Databáza | PostgreSQL 14–15 | PostgreSQL 13 a nižšie | Staršie verzie nie sú testované |
| OS | Ubuntu 22.04 LTS | Ubuntu 20.04 a staršie | Bez garancie podpory |
Takáto informácia šetrí hodiny hľadania.
4. Prepojiť požiadavky s dopadom
Technická hodnota sama o sebe nestačí.
Admin potrebuje vedieť aj dôsledok.
Napríklad:
- pri nepodporovanej verzii jazyka môže zlyhať časť funkcionality
- pri staršej databáze môže zlyhať migrácia
- pri slabšom hardvéri môže byť systém výrazne pomalší
Teda nie len „aké sú požiadavky“, ale aj „čo sa stane, ak ich nesplníme“.
5. Systémové požiadavky musia byť v administrátorskej príručke
Primárne miesto je administrátorská dokumentácia.
Nie:
- interný chat
- release ticket
- ústna dohoda
Admin potrebuje tieto informácie nájsť v dokumente, ktorý používa pri:
- inštalácii
- upgrade
- diagnostike
- plánovaní infraštruktúry
Pri zmene požiadaviek sa navyše táto zmena musí objaviť aj v release notes.
6. Rozlišovať on-premise a SaaS
Požiadavky nevyzerajú rovnako v každom type produktu.
On-premise:
- server
- databáza
- OS
- runtime
- disk
- sieť
SaaS:
- podporované prehliadače
- minimálne verzie klientskych aplikácií
- sieťové obmedzenia
- API kompatibilita
Admin potrebuje vedieť, ktorý typ reality rieši.
Príklad z praxe, ako to má byť zdokumentované
Namiesto neurčitého:
Systém vyžaduje aktuálnu verziu programovacieho jazyka.
má byť uvedené:
| Položka | Hodnota |
| Komponent | Programovací jazyk / runtime |
| Minimálna podporovaná verzia | 3.10 |
| Odporúčaná verzia | 3.11 |
| Nepodporované verzie | nižšie ako 3.10, vyššie ako 3.11 bez overenia |
| Riziko | Pri novšej verzii môže dôjsť k nekompatibilite s knižnicou X a zlyhaniu funkcionality Y |
| Overenie po nasadení | spustiť smoke test scenára Y |
Toto už nie je formálny zápis.
To je použiteľná administrátorská dokumentácia.
Mini checklist
- Sú systémové požiadavky v admin príručke, nie mimo nej?
- Sú oddelené minimálne a odporúčané hodnoty?
- Sú uvedené presné verzie softvéru a závislostí?
- Sú uvedené aj nepodporované verzie?
- Je pri každej kritickej položke vysvetlený dopad?
- Sú zmeny požiadaviek prepojené s release notes?
- Vie tester podľa dokumentácie overiť hraničné prostredie?
Ak nie, požiadavky nie sú dostatočne zdokumentované.
Prepojenie na kvalitu a workflow
Systémové požiadavky nie sú príloha pre technikov.
Sú súčasť kvality produktu.
Pomáhajú odlíšiť:
- bug v aplikácii
- chybu konfigurácie
- nekompatibilitu prostredia
Z testerského pohľadu je to veľmi dôležité.
Môj príklad s verziou programovacieho jazyka to ukazuje presne:
kým nie sú jasné hranice podporovaného prostredia, tím nevie, čo vlastne testuje a čo vyhodnocuje.
A potom sa testovanie mení na detektívku.
Krátke zhrnutie
Systémové požiadavky nie sú technická formalita.
Sú odpoveď na otázku:
Na čom tento systém funguje, na čom už nie a aké sú dôsledky?
Admin musí vedieť:
- minimálne požiadavky
- odporúčané požiadavky
- presné verzie
- nepodporované prostredia
- dopady nekompatibility
Bez toho firma nerieši systém.
Rieši dohady.