Dokumentace k softwaru je prostě soubor článků. I ty však mohou být frustrující. Nejprve dlouho hledáte potřebnou instrukci. Pak se snažíte porozumět málo srozumitelnému textu. Děláte to, co je napsané, ale problém se neřeší. Hledáte další článek, jste nervózní… Po hodině se na vše vykašlete a odcházíte. Takto funguje špatná dokumentace. Co ji dělá takovou a jak to opravit – čtěte dál.
V naší staré dokumentaci bylo mnoho nedostatků. Už skoro rok ji přepracováváme, aby výše zmíněný scénář naše zákazníky netýkal. Podívejte se, a .
Problém 1. Nejasné, špatně napsané články
Když se v dokumentaci nedá najít smysl, jaký to má význam? Ale nikdo píše nejasné články úmyslně. Vznikají, když autor nepřemýšlí o publiku a cíli, plýtvá slovy a nekontroluje text na chyby.
- Publikum. Před napsáním článku je třeba přemýšlet o úrovni znalostí čtenáře. Je logické, že v článku pro nováčka by se neměly vynechávat základní kroky a technické termíny by měly být vysvětleny, zatímco v článku o raritní funkci, která je potřebná pouze pro profesionály, by se skutečnost PHP měla důkladně rozebrat.
- Cíl. Další věc, na kterou je dobré myslet předem. Autor by měl mít jasný cíl, určit užitečný účel článku a rozhodnout, co čtenář udělá po jeho přečtení. Pokud se to neudělá, vznikne popis kvůli popisu.
- Přílišná voda a chyby. Mnoho zbytečných informací a byrokratismů, chyby a tiskové chyby ztěžují pochopení. I když čtenář není gramatickým pedantem, nedbalost v textu jej může odradit.
Zvažte výše uvedené rady a články se stanou srozumitelnějšími – garantováno. Abyste to ještě více zlepšili, vezměte si k srdci naše .
Problém 2. Články neodpovídají na všechny otázky
Je špatné, když dokumentace nestíhá technický vývoj, neodpovídá na skutečné otázky a chyby v ní se neopravují po léta. To jsou problémy víc než autora, spíše organizace procesů ve firmě.
Dokumentace nestíhá vývoj
Funkce již byla vydaná, marketing plánuje ji propagovat, ale ukazuje se, že v dokumentaci stále není nový článek nebo překlad. Kvůli tomu jsme museli dokonce odložit vydání. Můžeme vysvětlovat všem, aby úkoly včas předávali technickým spisovatelům, ale to nebude fungovat. Pokud proces neautomatizujeme, situace se bude opakovat.
Zavedli jsme změny v YouTracku. Úkol na sepsání článku o nové funkci přistane technickému spisovateli ve stejný okamžik, kdy začne testování. Tehdy o ní také marketing dozví, aby se připravil na propagaci. Oznámení přicházejí také do našeho firemního messengeru Mattermost, takže novinky od vývojářů není možné přehlédnout.
Dokumentace neodráží požadavky uživatelů
Jsme zvyklí pracovat takto: funkce vyšla, my o ní informujeme. Popisujeme, jak ji povolit, zakázat a provádět jemná nastavení. Ale co když klient používá náš software způsobem, který jsme nečekali? Nebo má chyby, o kterých jsme nepřemýšleli?
Aby byla dokumentace co nejúplnější, doporučujeme analyzovat dotazy podpory, otázky na specializovaných fórech, dotazy ve vyhledávačích. Nejoblíbenější témata předat technickým spisovatelům, aby doplnili stávající články nebo napsali nové.
Dokumentace se nezdokonaluje
Je složité udělat vše najednou perfektní, chyby se stejně objeví. Můžeme doufat v zpětnou vazbu od klientů, ale stěží se budou hlásit ohledně každého překlepu, nepřesnosti nebo nejasného či nenalezeného článku. Kromě klientů dokumentaci čtou také zaměstnanci, a proto vidí stejné chyby. To lze využít! Je potřeba vytvořit podmínky, v nichž bude snadné hlásit problém.
Máme skupinu na interním portálu, kde zaměstnanci zanechávají komentáře, návrhy a nápady k dokumentaci. Potřebuje podpora článek, který neexistuje? Tester si všiml nepřesnosti? Partner si stěžoval manažerům rozvoje na chyby? Vše do této skupiny! Technickí spisovatelé něco opravují ihned, něco převádějí do YouTracku, něco berou na uvážení. Aby téma nezapadlo, čas od času připomínáme existenci skupiny a důležitost zpětné vazby.
Problém 3. Potřebný článek se musí dlouho vyhledávat
Článek, který nelze najít, není lepší než článek, který neexistuje. Motto dobré dokumentace by mělo být „Snadno se hledá, snadno se nachází“. Jak toho dosáhnout?
Upravit strukturu a určit princip výběru témat. Struktura by měla být co nejtransparentnější, aby se čtenář nezamýšlel nad tím, „Kde mohu tuto stránku najít?”. Pokud to shrneme, existují dva přístupy: od rozhraní a od úloh.
- Od rozhraní. Obsah zrcadlí sekce panelu. Tak to bylo ve staré dokumentaci ISPsystem.
- Od úloh. Názvy článků a sekcí odrážejí úkoly uživatelů; v nadpisech jsou téměř vždy slovesa a odpovědi na otázku „jak to udělat”. Nyní přecházíme na tento formát.
Ať už zvolíte jakýkoliv přístup, ujistěte se, že téma odpovídá dotazům uživatelů a je pokryto tak, aby uživatel jistě vyřešil svůj problém.
Nastavit centralizované vyhledávání. V ideálním světě by vyhledávání mělo fungovat i při překlepech nebo chybách v jazyce. Naše vyhledávání v Confluence zatím tohle nedokáže. Pokud máte mnoho produktů a dokumentace je obecná, přizpůsobte vyhledávání podle stránky, na které se uživatel nachází. V našem případě vyhledávání na hlavní stránce funguje pro všechny produkty, a pokud se nacházíte v konkrétní sekci, pak pouze pro články v ní.
Přidat obsah a „chléb“,. Je dobré, když na každé stránce existuje menu a chléb – cesta uživatele k aktuální stránce s možností vrátit se na jakoukoliv úroveň. Ve staré dokumentaci ISPsystem bylo třeba vyjít z článku, aby se dostali k obsahu. Bylo to nepohodlné, a proto jsme to v novém dokumentu opravili.
Usměrnit odkazy v produktu. Pokud uživatelé opakovaně přicházejí na podporu se stejnou otázkou, je rozumné přidat nápovědu s jejím řešením do rozhraní. Pokud máte informace nebo chápání, v jaký okamžik se uživatel setkává s problémem, můžete ho také informovat prostřednictvím zasílání zpráv. Tak prokážete péči a snížíte zátěž na podporu.
Vpravo v okně se zobrazuje odkaz na článek o nastavení DNSSEC v sekci správy domén ISPmanager
Nastavit křížové odkazy v rámci dokumentaceČlánky, které jsou mezi sebou propojeny, by měly být „zalinkovány“. Pokud jsou články v sekvenci, nezapomeňte na konci každého textu přidat šipky vpřed a vzad.
Pravděpodobně nejprve půjde člověk hledat odpověď na svou otázku nikoli k vám, ale do vyhledávače. Je nepříjemné, pokud tam z technických důvodů nebudou odkazy na dokumentaci. Takže se postarejte o vyhledávací optimalizaci.
Problém 4. Zastaralá sazba brání vnímání
Kromě špatných textů může dokumentaci zkazit i design. Lidé jsou zvyklí číst dobře sazené materiály. Blogy, sociální sítě, média – celý obsah je podáván nejen esteticky, ale i pohodlně pro čtení a příjemně na pohled. Proto je snadné pochopit bolest někoho, kdo vidí text jako na snímku níže.
V tomto článku je tolik screenshotů a zvýraznění, že nepomáhají, ale pouze brání vnímání (obr. je klikací)
Není dobré dělat z dokumentace longread s množstvím efektů, ale základní pravidla je třeba zohlednit.
Sazba. Určete šířku hlavního textu, font, velikost, nadpisy a okraje. Zapojte designéra, a abyste mohli přijmout práci nebo si poradili sami, přečtěte si knihu Артема Горбунова „Typografie a sazba“. V ní je představen pouze jeden pohled na sazbu, ale ten je zcela dostačující.
Zvýraznění. Určte, co vyžaduje akcent v textu. Obvykle to jsou cesty v rozhraní, tlačítka, vložení kódu, konfigurační soubory, bloky „Věnujte pozornost“. Určete, jaká budou zvýraznění těchto prvků a zafixujte to v předpisech. Mějte na paměti, že čím méně zvýraznění, tím lépe. Když je jich mnoho, text „šumí“. Šum vytvářejí i uvozovky, pokud jsou používány příliš často.
Snímek obrazovky. Dohodněte se s týmem, v jakých případech jsou potřebné screenshoty. Ilustrovat každý krok rozhodně není nutné. Velké množství screenshotů, včetně jednotlivých tlačítek, brání vnímání a kazí sazbu. Určete velikost a formát zvýraznění a popisků na screenech, zafixujte to v předpisech. Pamatujte, že ilustrace by vždy měly odpovídat napsanému a být aktuální. Opět, pokud se produkt pravidelně aktualizuje, sledovat každou změnu bude složité.
Délka textu. Vyhněte se příliš dlouhým článkům. Rozdělte je na části, a pokud to není možné, přidejte na začátek článku obsah s kotvovými odkazy. Jednoduchý způsob, jak článek vizuálně zkrátit, je skrýt technické detaily potřebné úzkému okruhu čtenářů pod spoilerem.
Formáty. Kombinujte v článcích několik formátů: text, video a obrázky. To zlepší vnímání.
Nesnažte se zakrýt problémy hezkým designem. Upřímně, doufali jsme, že "obal" zachrání zastaralou dokumentaci - nepodařilo se. V textech bylo tolik vizuálního šumu a zbytečných podrobností, že směrnice a nové uspořádání byly bezmocné.
Mnohé z výše uvedeného bude určeno platformou, kterou používáte pro dokumentaci. U nás je to například Confluence. S ním jsme také museli trochu laborovat. Pokud vás to zajímá, přečtěte si příběh našeho webového vývojáře: .
Jak začít zlepšení a jak přežít
Pokud je vaše dokumentace stejně rozsáhlá jako ta od ISPsystem a nevíte, od čeho se začít, začněte s nejzávažnějšími problémy. Klienti dokumentaci nechápou - zaměřte se na zlepšení textů, vytvořte směrnice, školte autory. Dokumentace není aktuální - zaměřte se na vnitřní procesy. Začněte s nejpopulárnějšími články o nejžádanějších produktech: ptejte se podpory, podívejte se na analýzu webu a hledání v vyhledávačích.
Připravte se - nebude to snadné. A ani rychlé to pravděpodobně nebude. Snad, pokud právě začínáte a hned to děláte správně. Jedno víme jistě - časem to bude lepší. Ale proces nikdy neskončí :-).
Zdroj: habr.com
