Dokumentácia k softvéru je vlastne len súbor článkov. Ale aj tieto môžu byť frustrujúce. Najprv dlho hľadáte správny návod. Potom sa snažíte pochopiť nejasný text. Robíte to, čo je napísané, a problém sa nerieši. Hľadáte iný článok, nervujete sa... O hodinu sa na všetko vykašlete a odídete. Takto funguje zlá dokumentácia. Čo ju robí takou a ako to opraviť — čítajte ďalej.
V našej starej dokumentácii bolo veľa nedostatkov. Už takmer rok ju prepracovávame, aby sa popísaný scenár netýkal našich klientov. Pozrite sa, a .
Problém 1. Nejasné, zle napísané články
Ak sa v dokumentácii nedá orientovať, aký má zmysel? Ale nikto nenapíše nejasné články zámerne. Vznikajú, keď autor nepremýšľa o publiku a cieľoch, píše nezmysly a nekontroluje text na chyby.
- Publikum. Pred písaním článku je potrebné zamyslieť sa nad úrovňou prípravy čitateľa. Je logické, že v článku pre začiatočníka by sa nemali vynechávať základné kroky a technické pojmy by nemali zostať bez vysvetlenia, zatiaľ čo v článku o zriedkavej funkcii, ktorá je potrebná len pre profesionálov, by sa nemalo rozoberať, čo znamená slovo PHP.
- Cieľ. Ešte jedna vec, o ktorej je dobré premýšľať vopred. Autor by mal mať jasný cieľ, určiť užitočnú akciu článku a zistiť, čo čitateľ urobí po jeho prečítaní. Ak sa to neurobí, vznikne opis len tak pre opis.
- Zbytočné informácie a chyby. Množstvo zbytočných informácií a byrokratizmov, chyby a preklepy narúšajú vnímanie. Aj keď čitateľ nie je gramársky purista, nepozornosť v texte ho môže odradiť.
Zohľadnite rady vyššie a články sa stanú zrozumiteľnejšími — to je zaručené. Aby ste to ešte zlepšili, vezmite na vedomie našich .
Problém 2. Články neodpovedajú na všetky otázky
Je zlé, keď dokumentácia nedokáže držať krok s vývojom, neodpovedá na reálne otázky a chyby v nej sa neopravujú roky. Toto sú problémy nielen autora, ale skôr organizácie procesov vnútri spoločnosti.
Dokumentácia nedokáže držať krok s vývojom
Funkcia je už v release, marketing ju plánuje propagovať, a ukazuje sa, že nového článku alebo prekladu stále niet v dokumentácii. Kvôli tejto situácii sme museli odložiť vydanie. Môžeme koľkokrát požiadať všetkých, aby včas posielali úlohu technickým spisovateľom, ale to nebude fungovať. Ak proces neautomatizujeme, situácia sa bude opakovať.
Zmenili sme YouTrack. Úloha na napísanie článku o novej funkcii ide technickému spisovateľovi v okamihu, keď sa začne s testovaním. Vtedy sa o nej dozvie aj marketing, aby sa mohol pripraviť na propagáciu. Oznámenia prichádzajú aj do firemného messengeru Mattermost, takže je nemožné prehliadnúť novinky od vývojárov.
Dokumentácia neodráža požiadavky používateľov
Sme zvyknutí pracovať takto: funkcia vyšla, my o nej hovoríme. Opíšeme, ako ju zapnúť, vypnúť, urobiť jemné nastavenia. Ale čo ak klient používa náš softvér inak, než sme predpokladali? Alebo ak sa vyskytnú chyby, na ktoré sme nepomysleli?
Aby bola dokumentácia čo najúplnejšia, odporúčame analyzovať požiadavky na podporu, otázky na tematických fórach, dotazy vo vyhľadávačoch. Najpopulárnejšie témy poslať technickým spisovateľom, aby doplnili existujúce články alebo napísali nové.
Dokumentácia sa nezdokonaľuje
Je ťažké urobiť to dokonale naraz, chyby sa aj tak vyskytnú. Môžeme dúfať v spätnú väzbu od klientov, ale ťažko povedať, či sa im bude chcieť oznámiť každú chybu, nepresnosť, nezrozumiteľný alebo nenašiel článok. Okrem klientov dokumentáciu čítajú aj zamestnanci, a teda vidia tie isté chyby. To môžeme využiť! Musíme len vytvoriť podmienky, za ktorých sa ľahko oznámi problém.
Máme skupinu na internom portáli, kde zamestnanci zanechávajú pripomienky, návrhy a nápady k dokumentácii. Podpora potrebovala článok, a ten nie je? Tester si všimol nepresnosť? Partner si sťažoval manažérom rozvoja na chyby? Všetko do tejto skupiny! Technickí spisovatelia niečo hneď opravia, niečo prenesú do YouTrack, niečo si vezmú na zamyslenie. Aby sa téma nezabudla, občas pripomíname existenciu skupiny a dôležitosť spätnej väzby.
Problém 3. Potrebný článok sa musí dlho hľadať
Článok, ktorý nemožno nájsť, nie je lepší ako článok, ktorý neexistuje. Mottom dobrej dokumentácie by mala byť fráza „Ľahko hľadať, ľahko nájsť“. Ako to dosiahnuť?
Usporiadať štruktúru a určiť princíp výberu tém. Štruktúra by mala byť maximálne transparentná, aby čitateľ nemusel rozmýšľať „Kde môžem nájsť tento článok?“. Ak to zhrnieme, existujú dva prístupy: od rozhrania a od úloh.
- Od rozhrania. Obsah duplikuje sekcie panelu. Tak to bolo v starej dokumentácii ISPsystem.
- Od úloh. Názvy článkov a sekcií odrážajú úlohy používateľov; v nadpisoch takmer vždy sú slovesá a odpovede na otázku „ako to urobiť“. Teraz prechádzame do takého formátu.
Bez ohľadu na prístup, ktorý si vyberiete, uistite sa, že téma zodpovedá požiadavkám používateľov a je spracovaná tak, aby používateľ presne vyriešil svoj problém.
Zaviesť centralizované vyhľadávanie. V ideálnom svete by malo vyhľadávanie fungovať, aj keď spravíte preklep alebo sa pomýlite v jazyku. Naše vyhľadávanie v Confluence zatiaľ týmto nemôže potešiť. Ak máte veľa produktov a dokumentácia je spoločná, prispôsobte vyhľadávanie stránke, na ktorej sa používateľ nachádza. V našom prípade vyhľadávanie na hlavnej stránke funguje pre všetky produkty a ak sa už nachádzate v konkrétnej sekcii, tak iba pre články v nej.
Pridať obsah a „chlebové omrvinky“. Je dobré, keď na každej stránke je menu a chlebové omrvinky — cesta používateľa k aktuálnej stránke s možnosťou návratu na akúkoľvek úroveň. V starej dokumentácii ISPsystem bolo potrebné vystúpiť z článku, aby ste sa dostali k obsahu. Bolo to nepríjemné, preto sme to v novej verzii opravili.
Rozmiestniť odkazy v produkte. Ak sa ľudia opakovane obracajú na podporu s rovnakou otázkou, je rozumné pridať nápovedu s jej riešením do rozhrania. Ak máte dáta alebo pochopenie, kedy používateľ narazí na problém, môžete ho tiež informovať e-mailom. Týmto prejavíte starostlivosť a zároveň znížite záťaž podpory.
Vpravo v okne s informáciami je odkaz na článok o nastavení DNSSEC v sekcii správy domén ISPmanager
Nastaviť krížové odkazy v rámci dokumentácieČlánky, které si vzájemně souvisejí, by měly být „prolinkovány“. Pokud články tvoří posloupnost, nezapomeňte na konci 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 do vyhledávače. Je nepříjemné, pokud tam z technických důvodů nebudou odkazy na dokumentaci. Proto se postarejte o optimalizaci pro vyhledávače.
Problém 4. Zastaralá typografie překáží vnímání
Kromě špatných textů může dokumentaci zkazit design. Lidé jsou zvyklí číst dobře zpracované materiály. Blogy, sociální sítě, média — veškerý obsah je prezentován nejen krásně, ale i pohodlně na čtení a příjemně oku. Proto lze snadno pochopit bolest člověka, který vidí text jako na screenshotu níže.
V tomto článku je tolik screenshotů a zvýraznění, že nepomáhají, ale pouze překážejí vnímání (obrázek je klikací)
Není dobré dělat z dokumentace longread s hromadou efektů, ale základní pravidla je třeba vzít v úvahu.
Typografie. Určete šířku hlavního textu, písmo, velikost, nadpisy a okraje. Zapojte designéra, a abyste mohli práci přijmout nebo se s tím vypořádat sami, přečtěte si knihu Artěma Gorbunova „Typografie a sazba“. V ní je představena pouze jedna z perspektiv na typografii, ale je zcela dostačující.
Zvýraznění. Určete, co vyžaduje akcenty v textu. Obvykle to je cesta v rozhraní, tlačítka, vložené kódy, konfigurační soubory, bloky „Věnujte pozornost“. Určete, jaká budou zvýraznění těchto prvků a zaznamenejte to v regulaci. Mějte na paměti, že čím méně zvýraznění, tím lépe. Když jich je mnoho, text „šumí“. Hluk vytváří dokonce i uvozovky, pokud jsou používány příliš často.
Screenshoty. Domluvte se s týmem, v jakých případech jsou potřeba screenshoty. Ilustrovat každý krok rozhodně není nutné. Velké množství screenshotů, včetně jednotlivých tlačítek, překáží vnímání a kazí typografie. Určete velikost a formát zvýraznění a popisků na screenschotech, zaznamenejte v regulaci. Pamatujte, že ilustrace vždy musí odpovídat napsanému a být aktuální. Opět, pokud se produkt pravidelně aktualizuje, sledovat každý detail bude obtížné.
Délka textu. Vyhnite sa príliš dlhým článkom. Rozdeľte ich na časti, a ak to nie je možné, pridajte na začiatok článku obsah s kotvovými odkazmi. Jednoduchý spôsob, ako spraviť článok vizuálne kratším, je skryť technické podrobnosti, ktoré sú potrebné len úzkemu publiku, pod spoilerom.
Formáty. Kombinujte v článkoch niekoľko formátov: text, video a obrázky. To zlepší vnímanie.
Nepokúšajte sa zakryť problémy pekným dizajnom. Úprimne, aj my sme dúfali, že "obal" zachráni zastaranú dokumentáciu — nevyšlo to. V textoch bolo toľko vizuálneho hluku a zbytočných podrobností, že regulácia a nový dizajn boli bezmocné.
Mnohé z vyššie uvedeného sa bude určovať platformou, ktorú používate pre dokumentáciu. U nás, napríklad, je to Confluence. S tým sme sa tiež museli pohrať. Ak vás zaujíma, prečítajte si príbeh nášho webového vývojára: .
Odkiaľ začať zlepšovania a ako prežiť
Ak je vaša dokumentácia taká rozsiahla ako u ISPsystem a neviete, za čo sa chytiť, začnite s najvážnejšími problémami. Klienti nechápu dokumentáciu — venujte sa zlepšeniu textov, vytvorte regulácie, školte autorov. Dokumentácia nie je aktuálna — zaoberajte sa vnútornými procesmi. Začnite s najpopulárnejšími článkami o najžiadanejších produktoch: opýtajte sa podpory, pozrite sa na analýzu stránky a dopyty vo vyhľadávačoch.
Hneď povedzme — nebude to ľahké. A rýchlo to tiež asi nepôjde. Skôr len ak práve začínate a robíte to hneď správne. Jedno vieme určite — časom to bude lepšie. Ale proces nikdy neskončí :-).
Zdroj: habr.com
