Výstupem aktivit malých, středních i velkých organizací jsou produkty, které se neobejdou bez produktové dokumentace. Proč?

Produktová dokumentace je ve většině případů dodávána s produktem. Obsahuje podrobnosti o práci s produktem, pokyny k jeho používání, vyloučení odpovědnosti a další důležité detaily týkající se produktu. Bylo by však naivní si myslet, že produktová dokumentace je jen leták nebo brožura, kterou najdete v krabici s výrobkem. Je to mnohem širší pojem. Produktová dokumentace není určena jen pro spotřebitele. Ta spotřebitelská zahrnuje minimálně nutné a také legislativou požadované informace, které se podle produktu významně liší. I samotná organizace potřebuje uchovávat produktovou dokumentaci. Představte si například automobilku. Kolik dokumentace musí o vozidle nezbytně existovat už od samotného návrhu. Ve vozidle přitom v přihrádce spolujezdce najdete pouze velmi stručnou příručku řidiče. Jinak tomu není ani u softwaru, kde dodavatel disponuje návrhem produktu, zdrojovými kódy, popisy infrastruktury a uživatel pracuje pouze s manuálem, který je často v mnoha jazykových mutacích, i když je produkt pro globální trh úplně totožný.

Dokumentace produktu v Confluence

Confluence je ideální nástroj pro systémovou dokumentaci, zejména pro interní použití v organizacích. Dokumentaci tvoří pracovníci organizace, kteří mají licenci na Confluence, a přistupují k ní členové týmů, kteří také vlastní licenci. Pokud potřebujete spolupracovat na dokumentaci s partnery nebo subdodavateli, doporučujeme využít Guest (hostovský) přístup. Jde o přístup, který není zpoplatněný. Je omezen na jeden Confluence prostor (space) a na jednoho licencovaného uživatele máte k dispozici až 5 hostovských přístupů. Host může v daném prostoru stránky prohlížet, vytvářet, editovat, komentovat…

Při tvorbě dokumentace je klíčovým krokem dobře promyšlená struktura prostorů. Jednou z možností je přidělit každému produktu vlastní prostor. Oprávnění pro licencované uživatele i hosty lze jednoduše nastavit podle konkrétního prostoru. Confluence navíc nabízí možnost umožnit přístup anonymním uživatelům, což znamená, že do vybraného prostoru může přistoupit kdokoliv bez potřeby účtu. Tímto způsobem lze efektivně publikovat uživatelské dokumentace pro veřejnost.

Mnohé fyzické produkty dnes již neobsahují tištěné příručky, ale odkazují na digitální verze pomocí URL či QR kódů. Často směřují na produktový web s uživatelskou příručkou. Avšak, pro technickou a rozsáhlou dokumentaci se webové šablony ukazují jako méně vhodné. Confluence a jiné specializované nástroje nabízejí mnohem lepší funkce pro správu rozsáhlé dokumentace a usnadňují distribuci informací uživatelům.

Jaké klíčové výhody Confluence nabízí?

• Kontrola verzí – udržování jednotlivých verzí dokumentace a porovnání mezi nimi (co přibylo, ubylo, změnilo se). Kdo je autorem změn a kdy je provedl. Možnost vrátit se ke starší verzi a pokračovat v úpravách.
• Šablony – nejenže urychlí práci, ale pomohou s udržováním struktury dokumentů.
• Spolupráce – je nezbytné, aby na jednom dokumentu ve stejném čase mohlo pracovat více autorů. Případně obsah připomínkovat a vést nad ním diskuse.
• Pokročilé vyhledávání – čím více produktů, tím více dokumentů. Určitě nastane okamžik, kdy budete hledat nejen podle názvu dokumentů, ale i podle jejich obsahu.
• Bezpečnost – pokud jde o interní dokumentace, určitě nechcete přijít o konkurenční výhodu, kterou by díky jejich zveřejnění mohl získat soupeř.
• Zálohování – jistě nechcete přijít o data. Ani o dokument, který máte právě rozpracovaný.

Přehledný strom stránek s pomocí Page Tree Visualization

Page Tree Visualization poskytuje jednoduchý a intuitivní způsob pro vizualizaci a pochopení struktury vašich stránek v Confluence.

• Jednoduchost – Uživatel pouze vloží makro aplikace do stránky a ta ihned zobrazí mapu procesů.
• Přehlednost – Jediným pohledem na stránku se uživateli zobrazí celý průběh procesu.
• Úspora času – Uživatel už nemusí kreslit mapu procesů v Confluence, aplikace ji nakreslí automaticky.
• Integrace – Aplikace se snadno integruje do Confluence a umožňuje uživatelům vytvářet, upravovat a sdílet vizualizace v rámci různých stránek a prostorů v Confluence.

Jaké typy dokumentací známe?

Systémová dokumentace

Používá se „interně“ vývojáři, designéry… Technická část je určena vysoce technickému publiku. Kromě textových popisů zahrnuje různé výkresy, modely a podobně. Systémová dokumentace může mít i obchodní část, která je určena obchodníkům, marketérům a souvisejícím rolím. Podstatou systémové dokumentace je, že není veřejně dostupná.

Systémovou dokumentaci u softwarových řešení bychom mohli dále členit například na:

• Požadavky na produkt
• UX design
• API dokumentace
• Popis architektury
• Zdrojový kód
• Produktová mapa
• Testovací plány

Benefity systémové dokumentace:

• Bez technické specifikace a designu by nebylo možné produkt vytvořit ani rozvíjet.
• Systémové dokumenty umožňují technickým a obchodním týmům spolupracovat při vývoji a marketingu.
• Při fluktuaci zaměstnanců pomáhá novým členům týmu urychlit pochopení produktu/služby.

Uživatelská dokumentace

Poskytuje koncovým uživatelům informace, které jsou nezbytné pro úspěšné používání produktu nebo služby. S ohledem na cílové publikum se příručky zaměřují na méně či více technické publikum. Příkladem jsou uživatelské příručky, příručky pro rychlý start a příručky pro odstraňování chyb.

Pro softwarový produkt by uživatelská dokumentace mohla zahrnovat:

• Uživatelský manuál
• Instalační manuál
• Tréninkový manuál
• Návod pro rychlý start
• „Troubleshooting guide“
• FAQs

Benefity uživatelské dokumentace:

• Zvyšuje hodnotu produktu
• „Odemyká“ potenciál produktu
• Buduje důvěru zákazníka
• Zvyšuje prodej, kde je klíčová zákaznická podpora
• Snižuje potřebu týmů zákaznické podpory

Jak tvořit kvalitní produktovou dokumentaci?

Vysvětlili jsme si ve zkratce, co je produktová dokumentace, jaké typy lze rozlišit a co vše zahrnují. Existuje několik základních kroků, které doporučuji dodržovat.

• Identifikujte cílovou skupinu – než začnete tvořit obsah, ptejte se sami sebe, kdo bude informace konzumovat. A to nejen s ohledem na úroveň odbornosti obsahu, ale především na potřebu, kterou má dokumentace naplnit.
• Strukturování – strukturování, kategorizace a segmentace dělají informace pro čtenáře čitelnějšími a stravitelnějšími.
• Nezapomeňte na úvodní popis – výsledný dokument může být velmi rozsáhlý. Proto je vhodné hned na úvod produkt stručně popsat, i když další části dokumentu jsou velmi technické a odborné.
• Buďte struční – uvádějte pouze nezbytné informace, vyhněte se nepodstatným a nesouvisejícím informacím.
• Používejte šablony – pokud vytváříte dokumenty opakovaně, určitě svou efektivitu zvýšíte pomocí předdefinovaných šablon.

Kde tvořit produktovou dokumentaci?

Existuje mnoho dokumentačních nástrojů. Který zvolit? V tomto článku se zabýváme pouze Confluence. Ale volba nástroje závisí například na:

• Typu dokumentů, které potřebujete vytvářet
• Potřebě distribuovat dokumenty interně/externě.

V případě Confluence můžeme doporučit i její rozšíření aplikací Refined for Confluence. Prostory a stránky, se kterými pracuje Confluence, jsou tímto rozšířeny o pohled, který aplikace nazývá „Site“. Jde o nadstavbu, kterou bychom mohli nazvat i jako rozcestník. Pod sebou totiž může sdružovat několik prostorů, odkazovat na ně nebo na externí zdroje. Domovská stránka má vlastní editor, ve kterém administrátoři nastavují téma (vzhled pozadí, styl ikon, písma…) a konfigurují moduly, z nichž se skládá. Moduly si můžeme představit jako části skládačky, ze kterých si rozcestník sestavíme. Modulů je pro autory obsahu celá řada a svou formou podporují obsah nebo funkci, kterou právě potřebujeme.

Marek Vejrosta

Atlassian konzultant

Pokud potřebujete pomoc od expertů se zavedením nebo nastavením Jira a Confluence, nebo poradit, jak je co nejefektivněji využívat ve vaší firmě, neváhejte nás kontaktovat.

Naše řešení od Atlassian