Výstupom aktivít malých, stredných aj veľkých organizácií sú produkty, ktoré sa nezaobídu bez produktovej dokumentácie. Prečo?

Produktová dokumentácia je vo väčšine prípadov dodávaná s produktom. Obsahuje podrobnosti o práci s produktom, pokyny k jeho používaniu, vylúčenie zodpovednosti a ďalšie dôležité detaily týkajúce sa produktu. Bolo by však naivné si myslieť, že produktová dokumentácia je len leták alebo brožúra, ktorú nájdete v krabici s výrobkom. Je to oveľa širší pojem. Produktová dokumentácia nie je určená len pre spotrebiteľov. Tá spotrebiteľská zahŕňa minimálne nutné a tiež legislatívou požadované informácie, ktoré sa podľa produktu významne líšia. Aj samotná organizácia potrebuje uchovávať produktovú dokumentáciu. Predstavte si napríklad automobilku. Koľko dokumentácie musí o vozidle nevyhnutne existovať už od samotného návrhu. Vo vozidle pritom v priehradke spolujazdca nájdete iba veľmi stručnú príručku vodiča. Inak to nie je ani pri softvéri, kde dodávateľ disponuje návrhom produktu, zdrojovými kódmi, popismi infraštruktúry a používateľ pracuje iba s manuálom, ktorý je často v mnohých jazykových mutáciách, aj keď je produkt pre globálny trh úplne totožný.

Dokumentácia produktu v Confluence

Confluence je ideálny nástroj na systémovú dokumentáciu, najmä pre interné použitie v organizáciách. Dokumentáciu tvoria pracovníci organizácie, ktorí majú licenciu na Confluence, a pristupujú k nej členovia tímov, ktorí tiež vlastnia licenciu. Ak potrebujete spolupracovať na dokumentácii s partnermi alebo subdodávateľmi, odporúčame využiť Guest (hosťovský) prístup. Ide o prístup, ktorý nie je spoplatnený. Je obmedzený na jeden Confluence priestor (space) a na jedného licencovaného užívateľa máte k dispozícii až 5 hosťovských prístupov. Hosť môže v danom priestore stránky prehliadať, vytvárať, editovať, komentovať…

Pri tvorbe dokumentácie je kľúčovým krokom dobre premyslená štruktúra priestorov. Jednou z možností je prideliť každému produktu vlastný priestor. Oprávnenia pre licencovaných používateľov aj hostí sa dajú jednoducho nastaviť podľa konkrétneho priestoru. Confluence navyše ponúka možnosť umožniť prístup anonymným používateľom, čo znamená, že do vybraného priestoru môže pristúpiť ktokoľvek bez potreby účtu. Takto sa dajú efektívne publikovať užívateľské dokumentácie pre verejnosť.

Mnohé fyzické produkty už dnes neobsahujú tlačené príručky, ale odkazujú na digitálne verzie pomocou URL či QR kódov. Často smerujú na produktový web s užívateľskou príručkou. Avšak, pre technickú a rozsiahlu dokumentáciu sa webové šablóny ukazujú ako menej vhodné. Confluence a iné špecializované nástroje ponúkajú omnoho lepšie funkcie pre spravovanie rozsiahlej dokumentácie a zjednodušujú distribúciu informácií používateľom.

Aké kľúčové výhody Confluence ponúka?

• Kontrola verzií – udržiavanie jednotlivých verzií dokumentácie a porovnanie voči sebe (čo pribudlo, ubudlo, zmenilo sa). Kto je autorom zmien a kedy ich vykonal. Možnosť vrátiť sa k staršej verzii a pokračovať v úpravách.
• Šablóny – nielenže urýchlia prácu, ale pomôžu s udržaním štruktúry dokumentov.
• Kolaborácia – je nevyhnutné, aby na jednom dokumente v rovnakom čase mohlo pracovať viac autorov. Prípadne obsah pripomienkovať a viesť nad ním diskusie.
• Pokročilé vyhľadávanie – čím viac produktov, tým viac dokumentov. Určite nastane okamih, kedy budete hľadať nielen podľa názvu dokumentov, ale aj podľa ich obsahu.
• Bezpečnosť – ak ide o interné dokumentácie, určite nechcete prísť o konkurenčnú výhodu, ktorú by vďaka ich zverejneniu mohol získať súper.
• Zálohovanie – určite nechcete prísť o dáta. Ani o dokument, ktorý máte práve rozpracovaný.

Prehľadný strom stránky aj za pomoci Page Tree Visualization

Page Tree Visualization poskytuje jednoduchý a intuitívny spôsob pre vizualizáciu a pochopenie štruktúry vašich stránok v Confluence.

• Jednoduchosť – Používateľ iba vloží makro aplikácie do stránky a tá ihneď zobrazí mapu procesov.
• Prehľadnosť – Jediným pohľadom na stránku sa používateľovi zobrazí celý priebeh procesu.
• Úspora času – Používateľ už nemusí kresliť mapu procesov v Confluence, aplikácia ju nakreslí automaticky.
• Integrácia – Aplikácia sa ľahko integruje do Confluence a umožňuje používateľom vytvárať, upravovať a zdieľať vizualizácie v rámci rôznych stránok a priestorov v Confluence.

Aké typy dokumentácií poznáme?

Systémová dokumentácia

Používa sa „interne“ vývojármi, dizajnérmi… Technická časť je určená vysoko technickému publiku. Okrem textových popisov zahŕňa rôzne výkresy, modely a podobne. Systémová dokumentácia môže mať aj obchodnú časť, ktorá je určená obchodníkom, marketérom a súvisiacim rolám. Podstatou systémovej dokumentácie je, že nie je verejne dostupná.

Systémovú dokumentáciu pri softvérových riešeniach by sme mohli ďalej členiť napríklad na:

• Požiadavky na produkt
• UX dizajn
• API dokumentácia
• Popis architektúry
• Zdrojový kód
• Produktová mapa
• Testovacie plány

Benefity systémovej dokumentácie:

1. Bez technickej špecifikácie a dizajnu by nebolo možné produkt vytvoriť ani rozvíjať.
2. Systémové dokumenty umožňujú technickým a obchodným tímom spolupracovať pri vývoji a marketingu.
3. Pri fluktuácii zamestnancov pomáha novým členom tímu urýchliť pochopenie produktu/služby.

Užívateľská dokumentácia

Poskytuje koncovým užívateľom informácie, ktoré sú nevyhnutné na úspešné používanie produktu alebo služby. S ohľadom na cieľové publikum sa príručky zameriavajú na menej či viac technické publikum. Príkladom sú užívateľské príručky, príručky pre rýchly štart a príručky pre odstraňovanie chýb.

Pre softvérový produkt by užívateľská dokumentácia mohla zahŕňať:

• Užívateľský manuál
• Inštalačný manuál
• Tréningový manuál
• Návod pre rýchly štart
• „Troubleshooting guide“
• FAQs

Benefity užívateľskej dokumentácie:

1. Zvyšuje hodnotu produktu
2.  „Odomyká“ potenciál produktu
3. Buduje dôveru zákazníka
4. Zvyšuje predaj – kde je kľúčová zákaznícka podpora
5. Znižuje potrebu tímov zákazníckej podpory

Ako tvoriť kvalitnú produktovú dokumentáciu?

Vysvetlili sme si v skratke, čo je produktová dokumentácia, aké typy možno rozlíšiť a čo všetko zahŕňajú. Existuje niekoľko základných krokov, ktoré odporúčam dodržiavať.

1. Identifikujte cieľovú skupinu – skôr než začnete tvoriť obsah, pýtajte sa sami seba, kto bude informácie konzumovať. A to nielen s ohľadom na mieru odbornosti obsahu, ale najmä na potrebu, ktorú má dokumentácia naplniť. Len ťažko bude jeden dokument slúžiť novým užívateľom, pokročilým, alebo dokonca implementátorom zložitých aplikácií.
2. Štrukturujte – štrukturalizácia, kategorizácia a segmentácia robia informácie pre čitateľa čitateľnejšími a stráviteľnejšími.
3. Nezabudnite na úvodný popis – výsledný dokument môže byť veľmi rozsiahly. Preto je vhodné hneď na úvod produkt stručne opísať, aj keď ďalšie časti dokumentu sú veľmi technické a odborné.
4. Buďte struční – uvádzajte len nevyhnutné informácie, vyhnite sa nepodstatným a nesúvisiacim informáciám.
5. Používajte šablóny – ak tvoríte dokumenty opakovane, určite svoju efektivitu zvýšite pomocou preddefinovaných šablón, ktoré môžu obsahovať aj jasné inštrukcie pre autorov dokumentu.

Kde tvoriť produktovú dokumentáciu?

Existuje mnoho dokumentačných nástrojov. Ktorý zvoliť? V tomto článku sa zaoberáme len Confluence. Ale voľba nástroja závisí napríklad od:

• Typu dokumentov, ktoré potrebujete vytvárať
• Potreby distribuovať dokumenty interne/externe.

V prípade Confluence môžeme odporučiť aj jej rozšírenie aplikáciou Refined for Confluence. Priestory a stránky, s ktorými pracuje Confluence, sú razom rozšírené o pohľad, ktorý aplikácia nazýva „Site“. Ide o nadstavbu, ktorú by sme mohli nazvať aj ako rozcestník. Pod sebou totiž môže zoskupovať niekoľko priestorov, odkazovať na ne alebo externé zdroje. Domovská stránka má vlastný editor, v ktorom administrátori nastavujú tému (vzhľad pozadia, štýl ikon, písma…), ale aj konfigurujú moduly, z ktorých pozostáva. Moduly si môžeme predstaviť ako kúsky skladačky, z ktorých si rozcestník zostavíme. Modulov je pre autorov obsahu celý rad a svojím typom podporujú obsah alebo funkciu, ktorú práve potrebujeme.

Marek Vejrosta
Atlassian konzultant

Ak potrebujete pomoc od expertov so zavedením či nastavením Jira a Confluence, alebo poradiť ako ich čo najefektívnejšie využívať vo vašej firme, tak nás neváhajte kontaktovať.

Naše Atlassian riešenia