Celý program začal už v neděli 30.8. společnou prohlídkou Prahy a registrační párty. Na tuhle konferenci pro sto lidí dorazili autoři technické dokumentace (technical writer), vývojáři a lidé, co dělají support nebo mají na starosti komunitu kolem svých produktů.

Celá komunita byla velmi otevřená a přátelská. Pokud je vám dokumentace blízká, zkuste se zapojit. Další zajímavostí je složení účastníků i přednášejících – na téhle konferenci byl vzácně vyrovnaný počet muži a ženy, což je příjemné a v IT vidět zřídka.

První den

Pokusím se shrnout, co mě zaujalo.

IMPOSTER NO MORE: How Tech Writers Can Shed Self-Doubt, Embrace Uncertainty, and Surf the Upcoming Swerve in Technical Documentation – Riona MacNamara

Přednáška zaměřená na syndrom podvodníka mě moc nezaujala, netušil jsem ani, že něco takového existuje. Ale jedna užitečná rada na závěr byla. Soustřeďte se na to, co děláte, ne na to, kdo jste.

Whatchamacallit: Controlled Vocabularies for Technical Writers – Emilie Boillat

Emilie měla zajímavou přednášku o všech typech kontrolovaných slovníků od štíků (free tags), množiny štítků (list of labels), slovníky (glossary), lexikon (thesaurus), taxonomy až po ontologii. Kromě rozdílů mezi jednotlivými typy popsala vhodné nástroje, jak si vyrobit příslušný typ slovníku a používat ho při tvorbě dokumentace.

Visual Documentation Language – Sonja Heinen

Podle přísloví jeden obrázek je za tisíc slov. Od obrázků k emoji. Vtipné byly některé emoji místo normálních textů.

Emotication? ?⌛? = runtime error. Awesome examples by @sonjaheinen at #WritetheDocs :-)

— María de Antón (@amalulla) August 31, 2015

Tested and Correct, How to Make Sure Your Documentation Keeps Working – Adam Dangoor

Adam zde byl s ClusteHQ, kde dokumentace obsahuje mnoho pokynů k instalaci pro různé platformy. Nevýhoda takové dokumentace je, že spoléhá většinou na tyto věci:

• paměť vývojářů, že pokud někde něco mění, mají upravit i dokumentaci
• pravidelnou kontrolu
• zpětnou vazbu od uživatelů

To je ale špatně. Paměť nefunguje spolehlivě. Máte lepší práci než stále dokola kontrolovat dokumentaci, zda funguje. Uživatelé vám žádnou zpětnou vazbu nedají a na váš produkt se prostě vykašlou.

Proto je potřeba dokumentaci testovat, kód a dokumentace musí být pospolu a spustitelné ukázky kódu v dokumentaci je potřeba mít otestované. Používají Sphinx a doporučoval projekt Wordish pro testování výstupů z shellu.

Lightning Talks

Následovala série lighting talks, slyšeli jsme, jak dělat dokumentaci k sestavování věcí (návody a la Ikea), představeny byly Alchemy CMS a projekt Corilla.

WTD 2015 Alchemy CMS

Nejzajímavější byl projekt Corilla, který původně vznikl v Redhatu. Corilla je nástroj pro editaci dokumentace v XML formátu s nástrojemi kolem toho. Autoři se rozhodli vytvořit startup a po odchodu z Redhatu se tomuto Open Source projektu věnují naplno.

Generating docs from APIs – Jamie Hannaford

Jamie se věnoval generování dokumentace z kódu v pythonu. Zvolil formát swagger, na kterém ukazoval, jak se toho dá využít od dokumentace až ke generování SDK v jiném jazyce, například v PHP.

• Slides

Inclusive Tech Docs – TechComm Meets Accessibility – Radina Matic

Radina se zaměřila na přístupnost dokumentace a o kolik vám to pomůže, pokud máte dokumentaci přístupnou. Nejde jen o zrakově postižené, ale i starší občany, kde se s věkem zvyšují nároky na přístupnost.

Documenting your Story – Crafting a good presentation – Chris Ward

Tato přednáška mě hodně bavila, Chris je skvělý řečník, uměl vtipně a poutavě vyprávět.

Hlavní body:

• pokud je moc textu na slidech, je to špatně
• max. 5 dobrých bodů na slidu
• nezapomeňte na barvy a kontrast
• kvalitní, smysluplné obrázky
• buďte si jistí sami sebou

Etiketa:

• přijďte včas, začněte přesně a nechte si čas na otázky
• pokud děláte demo, buďte připravení, pokud to jde, nespoléhejte na internet, připravte si video
• cvičte, bez praxe to prostě nejde

Vyprávějte příběh, snažte najít relevatní příběh k vašemu publiku. Poznejte svoje publikum a jejich problémy, najděte pro ně řešení.

Když to nevyjde, zkuste podplácení! Třeba trička a samolepky.

Free Your Mind and Your Docs Will Follow – Patrick Keegan

Patrick se soustředil na to, jak udělat dokumentaci, která bude technická a přitom vtáhne uživatele, zapojí ho do procesu, což není nikdy jednoduché.

Podobné téma jako tato přednáška: https://www.youtube.com/watch?v=MRnZFVCirQM

Gardening Open Docs – Florian Scholz & Jean-Yves Perrier

Přednáška lidí od Mozilly o jejich dokumentaci. Od monitoringu po systematickou práci, která je velmi podobná té, jakou mají zahradníci.

• Slides
• Rozšíření do firefoxu pro testování dokumentace

Druhý den

Po náročném večeru v The Pub se účastníci zase vrátili na přednášky v Klubu Lávka.

WTD 2015 Attendees

Judas Priest Ate My Scrum Master – Paul Adams

Paul v titulku přednášky zmiňuje známou kapelu a ScrumMastera, ale přednáška s tím vůbec nesouvisela. Autor rád šokuje a snaží se, abyste po jeho přednášce měli více otázek než odpovědí a myslím, že se mu to dobře dařilo.

Hlavním bodem přednášky byly zákony softwarového vývoje, které, jak ukázal, jsou mnohem univerzálnější, než si někteří myslí. Ať mluvíme o Conway Law, Lehman’s laws nebo jen Paretově pravidlu,

Before the docs: writing for user interfaces – Beth Aitman

Beth měla skvělou přednášku plnou ukázek o UI a jak texty a jejich copywriting (microcopy) pomáhají, pokud se tomu věnuje čas a úsilí. Ať jde o tlačítka, kontextový help nebo chybová hlášení.

• Blog autorky o této problematice

How to Write an Email – Elijah Caine

Elijah je velmi mladý a nezkušený, bohužel na přednášce to bylo vidět. Kromě problémů z kontrastem, kdy nebylo ze slidů nic vidět, tak podle mě hlavní cíl, a sice poradit jak organizovat emaily, jak šetřit svůj čas či jaké nástroje pomohou zefektivnit práci s emaily, v přednášce úplně chyběl.

• Slides

Back to the Future: What Can Documentarians Learn From The Past? – Jennifer Rondeau

Jennifer nás vzala na exkurzi do 70. let, kdy vznikaly první technické dokumentace. Příběh o prvních autorech technické dokumentace v Microsoftu.

Lightning Talks

Další serie byla plná zajímavých nápadů. Projekt Walkhub o jednoduché tvorbě tutorialu pro navigaci v aplikaci, nebo proč lidé lepí nálepky na svoje notebooky. Nejzajímavější mi ale přišel Troy Howard z Twitteru, který mluvil o měření dokumentace. Tým z twitteru má jen 4 tech writery na 2000 inženýrů, kteří se starají o produkty a Troyovy zkušenosti a náhled byly velmi zajímavé.

Další 2 přednášky (MacGyvering your docs a The Quest for scientific credit for software documentation) jsem vynechal, protože jsem celou dobu diskutoval s Troyem o jeho přednášce.

Writing for what matters. Writing for thinking. – Zdeněk Němec

Zdeněk se soustředil na dokumentaci API, na příkladu Github API dokumentace ukázal, že mu chybí fundamentální věci jako to, k čemu ta vlastní dokumentace je a kde jsou popsaná data, s kterými chcete přes API pracovat.

Osobně si myslím, že autoři dokumentaci (twitter, heroku, github) dělají spíše referenční příručky než dokumentaci.

• Slides

Screencasting 101 – Diana Potter

Diana pracuje v supportu, ukazovala nám, jak pracuje na screencastech, které umožňují zjednodušit jejich práci.

Práci na screecastu má rozdělenou:

• napsat scénář
• nahrát audio
• nahrát video
• dát to celé dohromady

Je dobré nahrávat po částech rozdělených dle aplikace. Když pak dojde ke změně v aplikaci, změní se jen část videa. Důležité je mít konzistentní nahrávací prostředí, abyste vše mohli kdykoliv opakovat. Tj. je nutné mít mikrofon ve stejné poloze a na stejném místě, na obrazovce mít stejné uspořádání a rozlišení, aby se každá nahrávka dala reprodukovat, ušetří to mnoho práce i času.

• Slides
• Chrome plugin pro stejné rozlišení na nahrávání

All roads might not lead to docs – Christina Elmore

Christina se soustředila na to, proč dokumenty vůbec vznikají a že bychom měli dobře znát důvod a účel dokumentu, než začneme psát, nebo raději vůbec nepsat. Je to zvláště důležité, pokud máte o dokumentech rozhodovat, co kdo má napsat a kam, jak to zařadit do struktury dokumentace apod.

• Poznámky k přednášce od autorky

Závěr

Celá konference se ukončila párty v Jazz Docku.

V příštím roce se má akce rozrůst na 250 účastníků. Sledujte konferenci na twitteru, ať vám neujdou žádné detaily. Doslechl jsem se, že také meetupy kolem Write The Docs by se mohly v Praze objevit.

WTD 2015 All People

Odkazy

• Autor fotografii – Jiří Folta
• Web Konference
• Poznámky v angličině od @sarahleeyoga