Softwarová dokumentace je pouze soubor článků. Ale i oni vás mohou přivést k šílenství. Nejprve strávíte dlouhý čas hledáním potřebných pokynů. Pak pochopíte nejasný text. Děláte, jak je napsáno, ale problém není vyřešen. Hledáte další článek, znervózníte... O hodinu později vše vzdáte a odejdete. Takhle funguje špatná dokumentace. Co to dělá takhle a jak to opravit - přečtěte si pod řezem.
V naší staré dokumentaci bylo mnoho nedostatků. Již téměř rok to předěláváme, aby se výše popsaný scénář nedotkl našich klientů. Dívej se, и .
Problém 1: Nejasné, špatně napsané články
Pokud dokumentaci nelze porozumět, jaký má smysl? Nikdo ale záměrně nepíše nesrozumitelné články. Stávají se, když autor nemyslí na publikum a účel, nalévá vodu a nekontroluje text, zda neobsahuje chyby.
- Publikum. Než začnete psát článek, musíte se zamyslet nad úrovní přípravy čtenáře. Je logické, že v článku pro začátečníky byste neměli přeskakovat základní kroky a nechávat odborné termíny bez vysvětlení, ale v článku o vzácné funkci, kterou potřebují jen profesionálové, byste měli vysvětlit význam slova PHP.
- terč. Ještě jedna věc, na kterou je třeba předem myslet. Autor si musí stanovit jasný cíl, určit užitečný efekt článku a rozhodnout, co čtenář po přečtení udělá. Pokud tak neučiníte, skončíte s popisem pro popis.
- Voda a brouci. Je tam spousta zbytečných informací a byrokracie, chyby a překlepy zasahují do vnímání. I když čtenář není gramatický nacista, nedbalost v textu ho dokáže rozhodit.
Zvažte výše uvedené tipy a články budou jasnější - zaručeno. Aby to bylo ještě lepší, použijte náš .
Problém 2. Články neodpovídají na všechny otázky
Je špatné, když dokumentace nedrží krok s vývojem, neodpovídá na skutečné otázky a chyby v ní nejsou opravovány roky. To jsou problémy ani ne tak autora, ale organizace procesů ve firmě.
Dokumentace nedrží krok s vývojem
Funkce je již ve verzi, marketing plánuje její pokrytí a pak se ukáže, že nový článek nebo překlad stále není v dokumentaci. Dokonce jsme kvůli tomu museli vydání odložit. Můžete požádat každého, aby předal úkoly technickým autorům včas, jak chcete, ale nebude to fungovat. Pokud proces není automatizován, situace se bude opakovat.
Provedli jsme změny ve službě YouTrack. Úkol napsat článek o nové funkci připadá na technického autora ve stejný okamžik, kdy se funkce začíná testovat. Poté se o tom marketing dozví, aby se připravil na propagaci. Oznámení přicházejí také do podnikového messengeru Mattermost, takže je prostě nemožné přehlédnout novinky od vývojářů.
Dokumentace neodráží požadavky uživatelů
Jsme zvyklí pracovat takto: objevila se funkce, mluvili jsme o ní. Popsali jsme, jak jej zapnout, vypnout a provést jemné úpravy. Ale co když klient používá náš software způsobem, který jsme neočekávali? Nebo má chyby, o kterých jsme nepřemýšleli?
Aby byla dokumentace co nejúplnější, doporučujeme analyzovat žádosti o podporu, dotazy na tematických fórech a dotazy ve vyhledávačích. Nejoblíbenější témata budou převedena na technické spisovatele, aby mohli doplňovat stávající články nebo psát nové.
Dokumentace se nezlepšuje
Je těžké to udělat hned dokonale, stále budou chyby. Můžete doufat ve zpětnou vazbu od zákazníků, ale je nepravděpodobné, že by nahlásili každý překlep, nepřesnost, nesrozumitelný nebo nenalezený článek. Kromě klientů čtou dokumentaci zaměstnanci, což znamená, že vidí stejné chyby. Tohle se dá použít! Stačí vytvořit podmínky, ve kterých bude snadné nahlásit problém.
Na interním portálu máme skupinu, kde zaměstnanci zanechávají připomínky, návrhy a nápady k dokumentaci. Potřebuje podpora článek, ale neexistuje? Všiml si tester nepřesnosti? Stěžoval si partner vývojovým manažerům na chyby? Všichni v této skupině! Techničtí autoři některé věci opraví hned, některé přenesou do YouTrack a jiným dají čas na rozmyšlenou. Aby téma neutichlo, čas od času existenci skupiny a důležitost zpětné vazby připomeneme.
Problém 3. Najít správný článek trvá dlouho.
Článek, který nelze najít, není o nic lepší než článek, který nelze najít. Heslem dobré dokumentace by mělo být „Snadné vyhledávání, snadné nalezení“. Jak toho dosáhnout?
Uspořádejte strukturu a určete princip pro výběr témat. Struktura by měla být co nejtransparentnější, aby si čtenář nemyslel: "Kde najdu tento článek?" Abychom to shrnuli, existují dva přístupy: z rozhraní az úkolů.
- Z rozhraní. Obsah duplikuje sekce panelu. To byl případ staré dokumentace systému ISP.
- Z úkolů. Názvy článků a rubrik odrážejí úkoly uživatelů; Názvy téměř vždy obsahují slovesa a odpovědi na otázku „jak na to“. Nyní přecházíme na tento formát.
Ať už zvolíte jakýkoli přístup, ujistěte se, že téma odpovídá tomu, co uživatelé hledají, a je pokryto způsobem, který konkrétně odpovídá na otázku uživatele.
Nastavte centralizované vyhledávání. V ideálním světě by vyhledávání mělo fungovat i tehdy, když překlepete nebo uděláte chybu v jazyce. Naše dosavadní hledání v Confluence nás tímto nemůže potěšit. Pokud máte mnoho produktů a dokumentace je obecná, přizpůsobte vyhledávání stránce, na které se uživatel nachází. V našem případě funguje vyhledávání na hlavní stránce u všech produktů, a pokud už jste v konkrétní sekci, tak pouze u článků v ní.
Přidejte obsah a strouhanku. Je dobré, když má každá stránka menu a drobečky – cestu uživatele na aktuální stránku s možností návratu na libovolnou úroveň. Ve staré dokumentaci ISPsystem jste museli článek opustit, abyste se dostali k obsahu. Bylo to nepohodlné, tak jsme to opravili v novém.
Umístěte odkazy do produktu. Pokud lidé přicházejí na podporu znovu a znovu se stejnou otázkou, má smysl přidat nápovědu s jejím řešením do rozhraní. Pokud máte data nebo přehled o tom, kdy má uživatel problém, můžete jej také upozornit pomocí seznamu adresátů. Ukažte jim zájem a sejměte zátěž z podpory.
Vpravo ve vyskakovacím okně je odkaz na článek o nastavení DNSSEC v sekci správy domén ISPmanageru
Nastavte křížové odkazy v dokumentaci. Články, které spolu souvisejí, by měly být „propojené“. Pokud jsou články po sobě jdoucí, nezapomeňte na konec každého textu přidat šipky vpřed a vzad.
S největší pravděpodobností člověk nejprve půjde hledat odpověď na svou otázku nikoli k vám, ale k vyhledávači. Je škoda, když tam z technických důvodů nejsou odkazy na dokumentaci. Postarejte se tedy o optimalizaci pro vyhledávače.
Problém 4. Zastaralé rozvržení narušuje vnímání
Kromě špatných textů může dokumentaci kazit i design. Lidé jsou zvyklí číst dobře napsané materiály. Blogy, sociální sítě, média – veškerý obsah je prezentován nejen krásně, ale také snadno čitelný a lahodící oku. Proto můžete snadno pochopit bolest člověka, který vidí text jako na obrázku níže.
V tomto článku je tolik screenshotů a zvýraznění, že nepomáhají, ale pouze narušují vnímání (obrázek je klikatelný)
Neměli byste dělat dlouhé čtení z dokumentace s hromadou efektů, ale musíte vzít v úvahu základní pravidla.
Rozložení. Určete šířku hlavního textu, písmo, velikost, nadpisy a odsazení. Najměte si designéra a chcete-li přijmout práci nebo ji udělat sami, přečtěte si knihu Artyoma Gorbunova „Typografie a rozvržení“. Představuje pouze jeden pohled na uspořádání, ale je zcela dostačující.
Přidělení. Určete, co v textu vyžaduje důraz. Obvykle se jedná o cestu v rozhraní, tlačítka, vložení kódu, konfigurační soubory, bloky „Poznamenejte si prosím“. Určete, jaké budou alokace těchto prvků a zaznamenejte je do předpisů. Mějte na paměti, že čím méně výbojů, tím lépe. Když je jich hodně, je text zašuměný. Dokonce i uvozovky vytvářejí šum, pokud jsou používány příliš často.
Obrázky. Dohodněte se s týmem, v jakých případech jsou screenshoty potřeba. Rozhodně není třeba ilustrovat každý krok. Velké množství screenshotů, vč. samostatná tlačítka, narušují vnímání, kazí rozložení. Určete velikost a také formát zvýraznění a podpisů na snímcích obrazovky a zaznamenejte je do předpisů. Pamatujte, že ilustrace by měly vždy odpovídat tomu, co je napsáno, a být relevantní. Opět platí, že pokud je produkt pravidelně aktualizován, bude obtížné sledovat všechny.
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 obsah s kotevními odkazy na začátek článku. Jednoduchý způsob, jak článek vizuálně zkrátit, je skrýt technické detaily potřebné pro úzký okruh čtenářů pod spoiler.
Formáty. Kombinujte ve svých článcích několik formátů: text, video a obrázky. Tím se zlepší vnímání.
Nesnažte se zakrýt problémy krásným rozložením. Upřímně, sami jsme doufali, že „obal“ zachrání zastaralou dokumentaci – nevyšlo to. Texty obsahovaly tolik vizuálního šumu a zbytečných detailů, že předpisy a nový design byly bezmocné.
Hodně z výše uvedeného bude určeno platformou, kterou používáte pro dokumentaci. Máme například Confluence. Taky jsem si s ním musel pohrát. V případě zájmu si přečtěte příběh našeho webového vývojáře: .
Kde se začít zlepšovat a jak přežít
Pokud je vaše dokumentace tak rozsáhlá jako ISPsystem a nevíte, kde začít, začněte s největšími problémy. Klienti dokumentu nerozumí - vylepšovat texty, vytvářet předpisy, školit pisatele. Dokumentace je zastaralá - postarejte se o interní procesy. Začněte nejoblíbenějšími články o nejoblíbenějších produktech: zeptejte se podpory, podívejte se na analýzy stránek a dotazy ve vyhledávačích.
Řekněme si hned – nebude to jednoduché. A je nepravděpodobné, že bude fungovat rychle. Pokud zrovna nezačínáte a neuděláte hned správnou věc. Jedna věc, kterou víme jistě, je, že se to časem zlepší. Proces ale nikdy neskončí :-).
Zdroj: www.habr.com