Dne 22. června proběhl v Akademii CZ.NIC historicky první námi pořádaný workshop pro technické dokumentaristy. Workshop může mít různá pojetí, ale nejvhodnější se mi zdál formát podobný konferencím, tedy série prezentací se závěrečnou diskuzí.
Tento typ akce nám umožnil sdílet naše zkušenosti, a využít tak principu vzájemného spoluvzdělávání. Zabývali jsme se procesem (systematikou) dokumentování a používaných nástrojů. Přestože jsem si dovolila stanovit téma sama, ukázalo se, že jsem neminula. Oproti očekávané komorní účasti se nakonec sešlo 15 účastníků, z nichž pět umožnilo nahlédnout pod dokumentaristickou pokličku svojí firmy. Pozvání k aktivní účasti (kromě nás) přijali představitelé firem RedHat, Kerio Technologies a NetSuite, a jeden nezávislý dokumentarista. Měla jsem radost z toho, že pozvání přijaly společnosti, které mají systém dokumentování zavedený již poměrně dlouhou dobu, a tudíž se mohly setkat s bohatou škálou praktických problémů. Společnými silami jsme poodhalili současnou praxi a trendy dokumentování jak v prostředí open-source software, tak i v komerčněji orientovaném prostředí proprietárního software převážně s agilními metodikami vývoje. To jsou dva nejvýraznější proudy se znatelnými odlišnostmi, neboť i do přístupu k dokumentování se promítá obchodní model organizace.
V komerčních společnostech se pořídí někdy i drahé nástroje, což se ale může vyplatit, a to zejména v případě WYSIWYG editorů XML. Ty usnadňují práci méně technicky zdatným textařům, aby mohli produkovat obsah přímo v XML a přitom nemuseli luštit nepřehledný kód, což je nejčastější argument, proč tento formát nepoužívat. Oproti ostatním formátům má však XML jednu zásadní výhodu: striktní strukturovanost umožňuje přesné strojové zpracování, které může být využito mnoha způsoby k dalšímu odlehčení dokumentaristů od rutiny, a zároveň již z povahy XML může být dále snadno rozšiřováno.
Oproti tomu v open-source sféře se obvykle sáhne po nástrojích, které vyvíjí komunita, a tudíž jsou volně k dispozici. Bohužel mezi těmito nástroji není stejně kvalitní WYSIWYG editor XML, takže je člověk často odkázán na úpravu surového XML v (byť kvalitních) textových editorech. To se však lidem často nelíbí, a hledají proto alternativy lidsky čitelnějšího značkování, mezi nimiž se využívají např. reStructuredText nebo AsciiDoc. U nich ovšem nemusí být přizpůsobení právě nejsnadnější.
Co však mají oba proudy společného, je obliba sémantiky, která umožňuje hlavně oddělit správu vzhledu od správy obsahu, a principu publikování z jednoho zdroje (single-sourcing), který napomáhá zejména k udržení konzistence obsahu přes několik výstupních formátů. Zde mohu jen konstatovat, že v tomto směru nevybočujeme. Téměř všechny zúčastněné firmy zpracovávají dokumentaci pro mezinárodní prostředí, tudíž v angličtině, a často se kloní k „dialektu“ zjednodušené angličtiny (simplified english), která má svoje opodstatnění a jasně stanovená pravidla.
Zajímavé také je, že se pokročilí dokumentaristé začínají v některých společnostech posouvat na trochu jiné pozice. Díky rozsáhlému průzkumu oblasti nutnému k psaní dokumentace se totiž stávají odborníky na danou oblast, a tudíž mohou fungovat jako jakýsi „advokát uživatele“ nebo tlumočník, který potřeby uživatele zprostředkuje („přeloží“) vývojářům, a mohou dojít až k bodu, kdy jsou schopni psát i samotné specifikace. Dále se často také podílí na user experience, zejména při návrhu textů uživatelského rozhraní. Myslím si, že tento poznatek může být užitečný našemu technickému oddělení, protože právě komunikace mezi našimi interními zákazníky a technickými odborníky představuje záležitost, v níž bychom se mohli výrazně zlepšit.
Posledním zajímavým poznatkem bylo automatizované testování dokumentace v RedHatu, kde zacházejí s opravdu velkými objemy textů. (Vždyť jen v Brně zaměstnávají 25 dokumentaristů!) Jedním z vodítek pro technickou dokumentaci bývá tzv. příručka stylu, která stanovuje konvence k dosažení jednotného jazyka a struktury. V RedHatu pojali tuto příručku spíš jako referenci a následně se jim podařilo ji přetvořit na nástroj Emender, který na základě klíčových slov kontroluje jazykový styl textů a pravděpodobně dokáže testovat i další aspekty dokumentace.
Po skončení workshopu jsme sesbírané prezentace vystavili on-line, můžete si je projít na této adrese. Také jsme účastníky požádali o vyplnění dotazníku a jeho výsledky nám potvrdily, že workshop měl skutečný úspěch. Někteří mluvčí sice volají po volnější ruce ve výběru témat a dalších drobných vylepšeních, ale celkově událost hodnotili vysokým počtem bodů (průměr 4,4 z 5).
Věřím tedy, že ačkoliv první, nejspíš to workshop nebude poslední, a možná že se CZ.NIC v průběhu času stane základnou pro společné aktivity nadšených dokumentaristů v České republice.