Je čtvrtek 14. června 2018 a já jedu na Technical Writers’ Exchange of Experience Workshop, který pořádá Zuzana Lena Ansorgová už třetím rokem po sobě v CZ.NIC v Praze. No vlastně nejedu, ale stojím. Stojím už hodinu v koloně na D5. A začínám být nervózní, že nestihnu začátek. Každopádně mám v autě spoustu času a hlavou mi běží včerejší rozhovor s truhlářem Martinem, který nám tenhle týden instaluje novou kuchyni:
„A co ty, Vendulo, co jsi vlastně dělala před mateřskou?“, zeptal se mě Martin.
„Dělám do počítačů“ snažila jsem se to odbýt.
„Hmm, tomu já vůbec nerozumím. A to jako programuješ?“ ptá se pochybovačně.
„Ne, jsem techwriter.“
„Co to je? O tom jsem v životě neslyšel…“
„Píšu dokumentaci k softwaru.“ pořád kouká trochu nechápavě. “Už jsi někdy potřeboval manuál? Třeba k nový televizi nebo k nábytku z IKEA?“
„My nábytkáři nemusíme Ikeu“, zamumlal a dodal přesně to, čeho jsem se od začátku bála: „TO MUSÍ BEJT NUDA, TY MANUÁLY JAKO.“
„Není to nuda“, bráním se jako už po stopadesáté. “Je docela zábava dostat do ruky produkt, vyzkoušet si ho, pohrát si s ním a hádat, jak asi funguje. Taky mě baví odhalovat chyby. Je to jako s těma obrázkama, kde se hledá pět rozdílů…“
„Hm, já k práci potřebuju zákazníky“, přemýšlí Martin.
„To já taky. Hodně mi záleží na tom, jestli je uživatel spokojenej, jestli našel, co hledal, a jestli mu návod pomohl.“
„Tak to pak jo, tomu už rozumím.“ odpověděl ne příliš přesvědčeně Martin.
„No a třeba zrovna zítra jedu na setkání techwriterů, kteří pracují vesměs tady v Čechách, ale přijede i jeden chlápek z Irska a budeme si povídat o tom, co se nám povedlo, kdo používá jaké nástroje, nebo s jakými obtížemi se setkáváme a jak je překonáváme. Tady v Čechách je nás málo, a právě proto se vždycky se na tuhle akci hrozně těším. Konečně si zase popovídám s lidmi, které trápí podobné problémy a žijí z podobných úspěchů jako já.“
A jak to ve čtvrtek nakonec dopadlo? Dorazila jsem nakonec i přes zácpu na D5 včas v 9:30 do hotelu Olšanka v Táboritské ulici, kde má CZ.NIC učebnu pro svou akademii. Protože má učebna i svou kuchyňku, mohli jsme se zde všichni pozdravit a ještě před začátkem se nadopovat dobrou kávou. Na stole bylo také připraveno sladké i slané pohoštění, takže bylo jasné, že o nás dnes bude skvěle postaráno.
V učebně jsem napočítala celkem asi 17 účastníků z firem RedHat, CZ.NIC, GoodData, Oracle/NetSuite, Dativery a dalších. Pořadatelka Lena Ansorgová nás krásně přivítala a seznámila nás s celým programem – osmi krátkými prezentacemi, diskusemi, přestávkami na popovídání si a společným obědem, což mám ráda, protože neformálně v kuchyňce často zjistím tu nejdůležitější informaci celého dne.
The Future of Content Delivery
První přednáškovou část zahájila sama Lena z CZ.NIC přednáškou nazvanou The Future of Content Delivery. Název, jakož i celá prezentace je v angličtině proto, že jsme mezi sebou měli i několik cizinců.
Lena byla loni na největší techwriterské konferenci tcworld ve Stuttgartu, kde ji zaujalo téma inteligentního doručování obsahu. V Německu se tohle téma řeší zejména v souvislosti s průmyslem 4.0. Představte si, že se v továrně na konkrétním přístroji uvolní matička a vy jste opravář, kterému pípne mobil na obědě se zprávou, že ten a ten přístroj nefunguje správně. Na tabletu se zobrazí 3D obrázek, kde je červeně vyznačená ona povolená matička, kterou je třeba utáhnout spolu s jednoduchou legendou, jak se k ní dostat. Po obědě se opravář jde na matičku podívat, předem ví, kterým nástrojem se má vybavit, a po utáhnutí matička ihned přímo v té dokumentaci přestane svítit. No a jak takovou chytrou dokumentaci vytvořit, o tom Lena povídala. Většina z nás se orientuje na dokumentaci softwaru. Proto by Lena ráda vytvořila prototyp, který by za pomocí stejných nástrojů, v tomto případě na ontologii použité na metadatech produktu a dokumentace, jednoduše zjišťoval změny v softwaru, na které se musí techwriter podívat a zdokumentovat je.
Documentation on Transition
Další přednáška se jmenovala Documentation on transition a prezentovala jí Marie Doleželová z RedHatu. Ještě si živě pamatuji její loňskou přednášku o dokumentaci, která pomáhala zrakově postiženým lidem nainstalovat a zprovoznit software, který jim umožňoval práci na operačním systému RedHat i přes jejich postižení. Ukazovala, jak RedHat mění jazyk pro psaní dokumentace, ale také strukturu textu a z původní na popis vlastností orientované dokumentace se RedHat obrací k modernější úkolově orientované. Zákazníci totiž od dokumentace dnes hlavně očekávají, že dostanou do ruky krátký návod, jak vyřešit konkrétní problém, nainstalovat software nebo jak nastavit konkrétní parametry.
Letos Maruška pokračovala v načatém tématu a ukázala nám další dokumentaci, a také se s námi podělila o problémy, které vzniknou, když změníte formát, ve kterém dokumentaci píšete. RedHat psal v XML DocBook a v současné době přechází na – v techwriterské komunitě stále oblíbenější – asciidoc. Ten je jednodušší, takže se RedHatu lépe daří integrovat open-source části dokumentace, kterou tvoří linuxová komunita, s tou oficiální od RedHatu.
Možná vás zajímá, proč techwriteři nepíší v běžném textovém procesoru. Důvodů je několik:
- Potřebujeme kvalitní výstup
- Potřebujeme psát v šablonách, protože když je nás víc, je dobré udržet jednotný styl článků
- Potřebujeme jeden zdroj a z něj generovat více formátů na výstupu – obvykle HTML a PDF, ale někdy třeba taky CHM.
SDK DOCs
Po první přestávce prezentovala Vendulka Lucáková z GoodData SDK DOCs – Developers & Writers in Coop Mode in GitHub.
Vendulka moc hezky a vtipně shrnula, jaké strasti techwriteři zažívají s vývojáři, a jak je složité vymyslet funkční workflow, kde si vývojáři a techwriteři nebudou vzájemně při práci překážet. V GoodData nakonec vymysleli docela smysluplný model:
- Vývojáři připraví návrh dokumentace a příklady použití (kód).
- Nastaví uzamčení kódu pro dokumentaci.
- Techwriteři upraví a doladí dokumentaci do finální podoby.
Pokud chtějí vývojáři změnit dokumentaci po uzamčení kódu, musí techwriterům zadat ticket do Jiry.
A já jim držím palce, aby jim tento postup dobře sloužil. Vendulka nám, doufám, příští rok poví, jak se jim postup osvědčil.
Promoting Technical Writing
Milan Navrátil z Oracle/NetSuite se pustil do tématu, které mě vzhledem k mému rannímu rozjímání v dopravní zácpě hodně zajímalo. Promoting Technical Writing. Ano tohle téma pálí nás všechny. Všichni pořád vysvětlujeme svoje povolání svým přátelům, rodině, v hospodě i ve vlaku, co to ten techwriter vlastně dělá. Milanovi se povedla opravdu krásná motivační řeč, kde vyzdvihl, jak krátký stručný návod může pomoci uživatelům vyřešit jejich problém nebo je dokonce naučí používat celý produkt.
CSS Paged Media
Odpoledne pokračovalo přednáškou Jirky Koska nazvanou CSS Paged Media. Na tu jsem se těšila nejvíc. V mém bývalém zaměstnání jsem totiž psala dokumentaci v XML DocBook a pak jsme zdroj generovali do PDF přes ConTeXovou šablonu – speciální ne moc dobře dokumentovanou verzi TeXu. Vždycky jsem se bála šablonu upravovat, protože když jsem něco změnila, skoro vždycky se změnilo i něco, co jsem nechtěla, padaly mi obrázky a tabulky mimo stránky, a prostě jsem vždycky toužila po tom, vyřešit to generování jednodušeji. Jirkova přednáška mě opravdu přesvědčila, že generování pomoc CSS je mnohem jednodušší a s předvídatelnějším výsledkem.
Collaborating With The Community
Tomáš Raděj z RedHatu si připravil téma Collaborating With The Community. Seznámil nás s nástroji, které při tvoření dokumentace používají a mě samotné se hodně líbilo, že kladl velký důraz na pohodlí uživatelů při používání dokumentace tím, že vzal dokumentaci komunity i tu oficiální, tvořenou v RedHatu a obě udržuje aktuální na obou místech. Takže uživatelé nemusí hledat na dvou různých místech, pokud potřebují pomoct.
Twice a User, Half a Developer
Předposlední přednášky se ujal Misha Ramendik taktéž z RedHatu. Zvolil si téma Twice a User, Half a Developer – Documenting Highly Technical Topics. Jeho přednáška mě donutila přemýšlet, jak moc je důležité znát dobře produkt, dobře ho otestovat a často znát i další prostředí, ve kterém produkt nasazujeme. Teprve potom je techwriter schopen správně se ptát, odhalovat chyby v raných verzích produktu a odhalovat problematická místa v nasazení, konfiguraci a používání software a včas na ně v dokumentaci upozornit uživatele.
WordPress as a Documentation System
Posledním krátkým příspěvkem na téma WordPress as a Documentation System jsem uzavřela odpolední přednáškový blok já. Povídala jsem o tom, že někdy stačí psát dokumentaci ve WordPressu. Zejména pokud dokumentujete cloudové produkty, které nevyžadují generování PDF formátu, může být tohle levná cesta pro firmy s jedním nebo dvěma writery.
Na závěr jsme se společně v atriu hotelu Olšanka vyfotili a rozjeli se domů.
A já odjížděla s úplně odlišnými myšlenkami, než s jakými jsem ráno přijížděla. Techwriting rozhodně není nudný! Je to multioborová disciplína, kde je třeba být:
- trochu učitelem a umět vysvětlovat složité věci jednoduše, jak o tom mluvil Milan
- trochu testerem a umět si zvídavě a otevřeně pohrát s produktem, který budete popisovat
- napůl developerem, jak podotkl Misha ve své přednášce, abyste se uměli developerů správně zeptat na funkčnost produktu
- trochu psychologem a mít dostatek empatie pro vžití se do role uživatele, který chce produkt používat
- trochu spisovatelem, protože všechno to musíte nakonec nějak sepsat a pokud možno bez chyb
- trochu sazečem a tiskařem, protože výstup musí nějak vypadat
- trochu diplomatem, protože ke své práci potřebujete pomoc od dalších lidí ve vaší společnosti, jak o tom vtipně mluvila Vendulka L.
- organizátorem, abyste uměli uspořádat workshop, jako Lena
A tenhle mix ve spojení s honěním termínů před vydáním, to je přesně to, co mě na práci techwritera fakt baví.