Technická dokumentace bez výmluv

Pojďme si říct, co je technická dokumentace a co dělá dobrý technický pisatel den co den. Tahle práce znamená propojit dva světy. Na jedné straně je klient, který chce sepsat všechno, aby propagoval svůj byznys a značku. Na druhé je zákazník, který chce všechno vysvětlené co nejjednodušeji. Jak vyhovět oběma? Kde je hranice?

Psaní dokumentace je moje práce, takže se s vámi podělím o rady, které mi pomáhají. Když je použijete, příště se vám na otázku „Četli jste náš návod?“ nevrátí odpověď „TLDR“.

Nejdřív si ujasněte, co klient ve skutečnosti chce. Pro někoho je důležité množství dokumentace, pro jiného menší objem, ale ve vysoké kvalitě. Jeden klient cílí na stávající zákazníky, druhý honí rychlý růst nových.

Takhle to zjišťuji:

Tahle část umí být složitá, ale zkuste přemýšlet jako zákazník a projděte si svůj vlastní návod krok za krokem. Zjistíte, že věci, které vám přišly samozřejmé, samozřejmé nejsou. Hlídejte si každé slovo a celou dobu používejte stejné formulace i pojmenování.

Taky pomáhá nechat návod přečíst kamaráda z oboru nebo zkušeného konzultanta. Všimnou si problémů, které už dávno nevidíte.

Pokud píšete složitější návod, který krok za krokem provádí nějakým nastavením, přidejte sekci „vyzkoušejte si to“. Ukážete tím, že všechno funguje a že jste si nastavení sami prošli. Zákazníky to uklidní, hlavně když test natočíte na video.

Vaše návody čtou zákazníci po celém světě. Pamatujte na to, než sáhnete po složitém obratu nebo dlouhé větě. Idiomy text okoření, žargon ho udělá důvěrnějším a buzzwordy se čtou hladce, ale v technickém psaní vždycky vyhraje jednoduchost. (Ano, v tomhle článku idiomy používám. Jinde si je prostě dovolit nemůžu.)

Zdi textu. Dlouhé věty, které problém popisují do detailu. Při čtení se v tom těžko orientuje. Zní vám to povědomě?

Držte to jednoduché a nakreslete, co popisujete. Diagram toku pomůže uživateli vidět, co získá, když se návodem řídí. Dobře se sem hodí UML diagram.

Obrázky mi posloužily dobře a krátká videa s mluveným slovem taky. Není to jen moje zkušenost. Podle studie, kterou zpracoval Adhan Kholis z Department of English Language Education v Indonésii, jdou studentům výsledky znatelně lépe, když výuka používá video nebo obrázky. Zhruba 90 procent informací přijímáme zrakem a mozek zpracuje obrázek mnohem rychleji než text.

Tyhle prvky rozbijí dlouhé texty a celý návod usnadní pochopit.

Zpětná vazba je všechno. Berte ji s nadhledem a vytěžte z ní maximum. Koho se vyplatí zeptat:

Zpětná vazba od lidí je důležitá, ale ne vždycky spolehlivá. Obecně platí, že lidé neradi dávají negativní zpětnou vazbu. Víc se o tom dočtete v tomto článku.

TIL: Proč je pro lidi tak těžké dávat i přijímat negativní zpětnou vazbu?

Obvyklá odpověď je náš sklon vnímat negativní podněty silněji. Psychologové i neurobiologové zjistili, že náš mozek je nastavený reagovat na negativní podněty rychleji, což nás kdysi drželo naživu. Pocit ohrožení spustí režim boj, nebo útěk, zaplaví krev adrenalinem, zkrátí reakční čas a vyhrotí emoce.

Proto se opřete i o tvrdá data z analytiky. Řeknou vám, kolik lidí návod přečetlo, jak dlouho u něj zůstali a kam šli dál. A pro technického pisatele nejcennější: dají vám zpětnou vazbu bez lidského faktoru.

Učte se z vlastních chyb a z otázek, které se pořád opakují. Znalostní báze udrží tyhle znalosti uvnitř firmy. Milují ji hlavně lidé z technické podpory: dejte jim místo, kam si ukládají, co zjistí, a ušetříte čas i peníze klienta. Na tom vydělají všichni.

Naučit se tahle pravidla zabere čas, klientovi stejně jako vám. Ale je lepší být upřímný a věnovat čas kvalitnímu výsledku než něco narychlo splácat.

Skutečný projekt potřebuje víc než kopírovat a vložit. Abyste si s klientem vybudovali důvěru, najděte společnou řeč a vezměte si z těchhle rad, co funguje.

Mohlo by vás také zajímat:

Zdroje: