Zažila som projekty, kde sa všetko riešilo v hlavách ľudí. Bez dokumentácie, bez systému, s neustálymi otázkami na seniorov.
Postupne som pochopila, že to nie je problém jednotlivcov. Je to problém toho, ako firma pracuje s informáciami a ako má nastavené procesy. Dokumentácia často nemá vyhradený čas, nevzniká priebežne a nemá ani reálnu podporu od manažmentu.
Preto sa dnes dokumentácii venujem systematicky. Nie ako textu, ale ako nástroju, ktorý drží projekt pohromade. Píšem, testujem a hľadám spôsob, ako dokumentáciu čistiť, zjednodušovať a prepájať s vývojom, supportom aj testovaním.
Cieľ je praktický: mať dokumentáciu, podľa ktorej sa dá pracovať bez telefonátu seniorovi a bez hádania, čo systém vlastne robí.
Dnes sa k tomu pridáva ďalšia vrstva – tímy si zvykajú spoliehať na AI. Preto má dokumentácia spĺňať ešte jednu podmienku: musí fungovať aj vtedy, keď AI nie je k dispozícii.
Ak má firma používať AI, musí mať najprv zvládnuté vlastné dáta. A dokumentácia je ich základ.
- ÚVOD DO TÉMY DOKUMENTÁCIE (MENTÁLNY RÁMEC)
- Manuál nie je manuál – pre koho vlastne píšeme dokumentáciu
- Čo sa deje vo firmách, kde dokumentácia neexistuje
- Core vs Custom: najväčší tichý problém dokumentácie v produktových firmách
- Ako to robiť v praxi: vrstvy dokumentácie
- Ako má vyzerať workflow projektu (Feature → Test → Dokumentácia → Release)
- Ako presvedčiť tím, ktorý dokumentáciu systematicky ignoruje
- USER STORY A AKCEPTAČNÉ KRITÉRIÁ (MOST MEDZI BIZNISOM A DOKUMENTÁCIOU)
- User story nie je špecifikácia – čo má a čo nemá obsahovať
- Ako písať testovateľné akceptačné kritériá
- Given–When–Then vs voľný text – čo je čitateľnejšie pre tím
- Funkčné vs nefunkčné požiadavky – prečo ich tímy často miešajú
- Najčastejšie chyby v akceptačných kritériách (nejasnosť, chýbajúce výnimky, miešanie riešenia s požiadavkou)
- Core vs Custom už na úrovni user story
- Ako z user story a akceptačných kritérií vznikajú testy, dokumentácia a release notes (Epic → Story → Task → Bug v Jire)
- Ako rozoznať dobré vs slabé user story a akceptačné kritériá (praktické ukážky)
- ŠPECIFIKÁCIA AKO ZÁKLAD CELEJ DOKUMENTÁCIE
- Špecifikácia je prvá dokumentácia
- Ako písať testovateľnú špecifikáciu
- Špecifikácia bez UI návrhu nie je kompletná
- Ako testovať špecifikáciu pred vývojom
- Core vs Custom už na úrovni špecifikácie
- Prepojenie špecifikácie → test cases → manuál → release notes
- Najčastejšie chyby v špecifikáciách a ich dopad na projekt (praktické ukážky)
- POUŽÍVATEĽSKÉ MANUÁLY (USER GUIDE)
- Ako písať používateľské manuály (aby ich ľudia naozaj čítali)
- Ako písať používateľský manuál tak, aby odolal novým verziám
- Ako písať používateľské manuály – príklady z praxe (čo funguje a čo nie)
- Core vs Custom na úrovni používateľského manuálu
- Univerzálna šablóna používateľského manuálu (core + custom vrstva)
- Ako pracovať so screenshotmi a vizuálnymi prvkami v manuáli
- Ako písať manuál pre rôzne úrovne používateľov (začiatočník vs pokročilý)
- Najčastejšie chyby v používateľských manuáloch a ich dopad na projekt (praktické ukážky)
- Praktická ukážka ako napísať návod na 1 funkciu z user story+akceptačné kritériá a špecifikácie požiadavky
- ADMINISTRÁTORSKÁ PRÍRUČKA
- Administrátorská príručka ≠ používateľský manuál
- Admin nie je jedna rola: cieľové skupiny a vrstvy dokumentácie
- Štruktúra administrátorskej príručky (pre rôzne typy adminov)
- Ako dokumentovať roly, práva a bezpečnosť
- Ako dokumentovať konfiguráciu systému a jej dopady
- Systémové požiadavky (minimálne HW/SW požiadavky) – čo musí vedieť admin
- Incidenty, logovanie a diagnostika
- Nasadenie, upgrade a rollback (čo nikdy nesmie chýbať)
- SLA, zodpovednosti a prevádzkové hranice systému
- Najčastejšie chyby v administrátorských príručkách a ich dopad na projekt (praktické ukážky)
- Univerzálna šablóna administrátorskej príručky (core + custom vrstvy)
- Praktická ukážka ako napísať návod na 1 funkciu z user story+akceptačné kritériá a špecifikácie požiadavky
- INTERNÉ MANUÁLY PRE TECHNICKÚ PODPORU
- Support manuál ≠ používateľský manuál
- Štruktúra jednej support položky (Symptóm → Príčina → Diagnostika → Riešenie)
- Ako písať symptómovo, nie funkčne
- Kedy vzniká support dokumentácia (workflow + Definition of Done)
- Incident ako zdroj znalostnej bázy
- Bug report ako zdroj support dokumentácie
- Logovanie a diagnostika
- Eskalačný model a hranice supportu
- Core vs Custom v support dokumentácii
- Workaroundy a dočasné riešenia – ako ich zapisovať, aby nepoškodili produkt
- Ako štruktúrovať support znalostnú bázu (tagy, názvy, vyhľadateľnosť)
- Univerzálna šablóna support položky (ready-to-use pre prax)
- Ako udržiavať support dokumentáciu aktuálnu (verzie, zastarané riešenia, archivácia)
- Support dokumentácia pripravená pre budúcu AI
- Ako merať efektivitu support dokumentácie
- Najčastejšie chyby v interných manuáloch a ich dopad na projekt (praktické ukážky)
- Praktické ukážky: 3–5 reálnych support scenárov (z user story + akceptačné kritériá + špecifikácia + bugy → hotové support položky)
- TECHNICKÁ DOKUMENTÁCIA
- Technická dokumentácia ≠ používateľský manuál
- Kontext systému – čo je systém a čo nie
- Architektúra systému – komponenty a komunikácia
- Ako zapisovať architektúru systému, aby sa podľa nej dalo pracovať
- Tok dát a životný cyklus dát
- Dátový model a databázová dokumentácia
- API dokumentácia – čo má obsahovať
- Autentifikácia, autorizácia a bezpečnosť
- Integrácie a externé závislosti
- Konfiguračné parametre a feature flags
- Chybové stavy a funkčné obmedzenia systému
- Performance, limity a škálovanie
- Monitoring, logovanie a observability
- Verziovanie technickej dokumentácie
- Core vs Custom v technickej dokumentácii
- Dokumentácia pre DevOps a infra tím
- Najčastejšie chyby v technickej dokumentácii a ich dopad na projekt (praktické ukážky)
- Praktická ukážka: ako čítať technickú dokumentáciu a overiť ju testovaním
- RELEASE NOTES
- Čo sú release notes a pre koho sú určené
- Rozdiel medzi internými a verejnými release notes
- Ako písať zmeny bez marketingovej vaty
- Breaking changes a ich komunikácia
- Prepojenie release notes s dokumentáciou
- Ako zabrániť chaosu v historických zmenách (archivácia vs aktuálny stav)
- Najčastejšie chyby v release notes a ich dopad na projekt (praktické ukážky)
- Praktická ukážka ako napísať návod na niekoľko funkciía z user story+akceptačné kritériá a špecifikácie požiadavky a bugov
- ZNALOSTNÁ BÁZA PRE CHATBOT / AI / RAG
- Ako štruktúrovať dokumentáciu pre AI
- Krátke jednoznačné odpovede vs dlhé odseky
- Core vs Custom ako kritický parameter pre AI
- Chunkovanie dokumentácie a modularita
- Konzistencia terminológie ako ochrana pred halucináciami
- Ako pripraviť dokumentáciu ako vstup pre RAG systém
- Najčastejšie chyby pri príprave dokumentácie pre AI (praktické ukážky)
- Praktická ukážka ako napísať návod na 1 funkciu z user story+akceptačné kritériá a špecifikácie požiadavky
- AKO TESTOVAŤ, ČI JE DOKUMENTÁCIA ZROZUMITEĽNÁ
- Dokumentácia sa má testovať rovnako ako softvér
- Testovanie používateľského manuálu
- Testovanie administrátorskej príručky
- Testovanie support manuálu
- Testovanie technickej dokumentácie
- Testovanie release notes
- Testovanie znalostnej bázy pre chatbot
- Konzistencia naprieč dokumentáciou
- Testovanie čitateľnosti a kognitívnej záťaže
- Testovanie aktuálnosti dokumentácie
- Univerzálny checklist pre testovanie dokumentácie
- Dokumentačný audit projektu – ako zistiť reálny stav firmy
- RIADENIE DOKUMENTÁCIE V PROJEKTE
- Ako udržiavať dokumentáciu aktuálnu (verzie, zastarané riešenia, archivácia)
- Ako merať efektivitu dokumentácie
- Ako nastaviť dokumentáciu ako súčasť Definition of Done
- Dokumentácia ako súčasť release procesu
- Kto zodpovedá za dokumentáciu (role v tíme)
- Dokumentácia ako súčasť Definition of Done (prečo bez nej nie je úloha hotová)
- PRÍLOHY, ŠABLÓNY, VZORY