Softvérová dokumentácia je len súbor článkov. Ale aj tie vás dokážu vyviesť z miery. Najprv strávite dlhý čas hľadaním potrebných pokynov. Potom pochopíte nejasný text. Robíš ako je napísané, ale problém nie je vyriešený. Hľadáte ďalší článok, znervózniete... O hodinu to všetko vzdáte a odídete. Takto funguje zlá dokumentácia. Čo to robí takto a ako to opraviť - prečítajte si pod rezom.
V našej starej dokumentácii bolo veľa nedostatkov. Už takmer rok ho prerábame, aby sa vyššie popísaný scenár nedotkol našich klientov. pozri, и .
Problém 1: Nejasné, zle napísané články
Ak dokumentácii nie je možné porozumieť, aký má zmysel? Nikto ale nepíše zámerne nezrozumiteľné články. Stávajú sa, keď autor nemyslí na publikum a účel, leje vodu a nekontroluje chyby v texte.
- Publikum. Pred napísaním článku sa musíte zamyslieť nad úrovňou prípravy čitateľa. Je logické, že v článku pre začiatočníka by ste nemali preskočiť základné kroky a nechať odborné výrazy bez vysvetlenia, ale v článku o vzácnej funkcii, ktorú potrebujú len profesionáli, by ste mali vysvetliť význam slova PHP.
- Cieľ. Ešte jedna vec, na ktorú treba myslieť vopred. Autor si musí stanoviť jasný cieľ, určiť užitočný efekt článku a rozhodnúť sa, čo urobí čitateľ po jeho prečítaní. Ak to neurobíte, skončíte s popisom kvôli popisu.
- Voda a chrobáky. Je tu veľa zbytočných informácií a byrokracie, chyby a preklepy zasahujú do vnímania. Aj keď čitateľ nie je gramatický nacista, neopatrnosť v texte ho dokáže vytočiť.
Zvážte vyššie uvedené tipy a články budú jasnejšie - zaručené. Aby to bolo ešte lepšie, použite náš .
Problém 2. Články neodpovedajú na všetky otázky
Je zlé, keď dokumentácia nedrží krok s vývojom, neodpovedá na skutočné otázky a chyby v nej nie sú roky opravené. To nie sú ani tak problémy autora, ale organizácie procesov vo firme.
Dokumentácia nedrží krok s vývojom
Funkcia je už vo vydaní, marketing plánuje pokryť ju a potom sa ukáže, že nový článok alebo preklad stále nie je v dokumentácii. Dokonca sme kvôli tomu museli vydanie odložiť. Môžete požiadať každého, aby odovzdal úlohy technickým autorom načas, koľko chcete, ale nebude to fungovať. Ak proces nie je automatizovaný, situácia sa bude opakovať.
Urobili sme zmeny na YouTrack. Úloha napísať článok o novej funkcii pripadne technickému autorovi v tom istom momente, keď sa funkcia začne testovať. Potom sa o tom marketing dozvie, aby sa pripravil na propagáciu. Upozornenia prichádzajú aj do podnikového messengeru Mattermost, takže je jednoducho nemožné prehliadnuť novinky od vývojárov.
Dokumentácia nezohľadňuje požiadavky používateľov
Sme zvyknutí pracovať takto: objavila sa funkcia, hovorili sme o nej. Popísali sme, ako ho zapnúť, vypnúť a vykonať jemné úpravy. Čo ak však klient používa náš softvér spôsobom, ktorý sme neočakávali? Alebo má chyby, na ktoré sme nemysleli?
Aby bola dokumentácia čo najúplnejšia, odporúčame analyzovať žiadosti o podporu, otázky na tematických fórach a dopyty vo vyhľadávačoch. Najpopulárnejšie témy budú prenesené na technických spisovateľov, aby mohli doplniť existujúce články alebo napísať nové.
Dokumentácia sa nezlepšuje
Je ťažké to urobiť okamžite dokonale; stále budú chyby. Môžete dúfať v spätnú väzbu od zákazníkov, ale je nepravdepodobné, že by nahlásili každý preklep, nepresnosť, nezrozumiteľný alebo nenájdený článok. Dokumentáciu čítajú okrem klientov aj zamestnanci, čo znamená, že vidia rovnaké chyby. Toto sa dá použiť! Musíte len vytvoriť podmienky, v ktorých bude ľahké nahlásiť problém.
Na internom portáli máme skupinu, kde zamestnanci zanechávajú pripomienky, návrhy a nápady na dokumentáciu. Potrebuje podpora článok, ale neexistuje? Všimol si tester nepresnosť? Sťažoval sa partner vývojovým manažérom na chyby? Všetci v tejto skupine! Technickí autori niektoré veci opravia hneď, niektoré prenesú do YouTrack a iným dajú čas na premyslenie. Aby téma neutíchla, z času na čas pripomíname existenciu skupiny a dôležitosť spätnej väzby.
Problém 3. Nájsť správny článok trvá dlho.
Článok, ktorý sa nedá nájsť, nie je o nič lepší ako článok, ktorý sa nedá nájsť. Heslo dobrej dokumentácie by malo byť „Jednoduché vyhľadávanie, ľahké nájdenie“. Ako to dosiahnuť?
Usporiadajte štruktúru a určte princíp výberu tém. Štruktúra by mala byť čo najtransparentnejšia, aby si čitateľ nemyslel: „Kde nájdem tento článok?“ Aby sme to zhrnuli, existujú dva prístupy: z rozhrania az úloh.
- Z rozhrania. Obsah duplikuje sekcie panela. Toto bol prípad starej dokumentácie ISPsystem.
- Z úloh. Názvy článkov a sekcií odrážajú úlohy používateľov; Názvy takmer vždy obsahujú slovesá a odpovede na otázku „ako na to“. Teraz prejdeme na tento formát.
Bez ohľadu na to, aký prístup si vyberiete, uistite sa, že téma je relevantná pre to, čo používatelia hľadajú, a je pokrytá spôsobom, ktorý konkrétne rieši otázku používateľa.
Nastavte centralizované vyhľadávanie. V ideálnom svete by vyhľadávanie malo fungovať aj vtedy, keď preklepnete alebo urobíte chybu v jazyku. Naše doterajšie hľadanie v Confluence nás týmto nemôže potešiť. Ak máte veľa produktov a dokumentácia je všeobecná, prispôsobte vyhľadávanie stránke, na ktorej sa používateľ nachádza. V našom prípade funguje vyhľadávanie na hlavnej stránke pri všetkých produktoch a ak sa už nachádzate v konkrétnej sekcii, tak len pri článkoch v nej.
Pridajte obsah a strúhanku. Je dobré, keď má každá stránka menu a strúhanku – cestu používateľa na aktuálnu stránku s možnosťou návratu na ľubovoľnú úroveň. V starej dokumentácii ISPsystem ste museli opustiť článok, aby ste sa dostali k obsahu. Bolo to nepohodlné, tak sme to opravili v novom.
Umiestnite odkazy do produktu. Ak ľudia prichádzajú na podporu znova a znova s tou istou otázkou, má zmysel pridať nápovedu s jej riešením do rozhrania. Ak máte údaje alebo informácie o tom, kedy má používateľ problém, môžete ho upozorniť aj prostredníctvom zoznamu adries. Ukážte im záujem a zbavte ich podpory.
Vpravo vo vyskakovacom okne je odkaz na článok o nastavení DNSSEC v sekcii správy domén v ISPmanager
Nastavte krížové odkazy v dokumentácii. Články, ktoré spolu súvisia, by mali byť „prepojené“. Ak sú články za sebou, nezabudnite na koniec každého textu pridať šípky dopredu a dozadu.
S najväčšou pravdepodobnosťou človek najskôr pôjde hľadať odpoveď na svoju otázku nie vám, ale vyhľadávaču. Je škoda, ak tam z technických príčin nie sú odkazy na dokumentáciu. Postarajte sa teda o optimalizáciu pre vyhľadávače.
Problém 4. Zastarané rozloženie zasahuje do vnímania
Okrem zlých textov môže dokumentáciu pokaziť aj dizajn. Ľudia sú zvyknutí čítať dobre napísané materiály. Blogy, sociálne siete, médiá – všetok obsah je prezentovaný nielen krásne, ale aj ľahko čitateľný a príjemný pre oči. Preto môžete ľahko pochopiť bolesť osoby, ktorá vidí text ako na obrázku nižšie.
V tomto článku je toľko screenshotov a zvýraznení, že nepomáhajú, ale iba narúšajú vnímanie (obrázok je klikateľný)
Nemali by ste robiť dlhé čítanie z dokumentácie s množstvom efektov, ale musíte vziať do úvahy základné pravidlá.
Rozloženie. Určite šírku, typ písma, veľkosť, nadpisy a výplň. Najmite si dizajnéra a ak chcete prijať prácu alebo to urobiť sami, prečítajte si knihu Artyoma Gorbunova „Typography and Layout“. Predstavuje len jeden pohľad na dispozičné riešenie, ktorý je však úplne postačujúci.
Alokácie. Určite, čo si v texte vyžaduje dôraz. Typicky je to cesta v rozhraní, tlačidlá, vložené kódy, konfiguračné súbory, bloky „Poznámka“. Určte, aké budú pridelenia týchto prvkov a zaznamenajte ich do predpisov. Majte na pamäti, že čím menej výtoku, tým lepšie. Keď je ich veľa, text je zašumený. Dokonca aj úvodzovky vytvárajú šum, ak sa používajú príliš často.
Obrázky. Dohodnite sa s tímom, v akých prípadoch sú potrebné snímky obrazovky. Rozhodne netreba ilustrovať každý krok. Veľké množstvo screenshotov, vr. samostatné tlačidlá, zasahujú do vnímania, kazia rozloženie. Určite veľkosť, ako aj formát zvýraznení a podpisov na snímkach obrazovky a zaznamenajte ich do predpisov. Pamätajte, že ilustrácie by mali vždy zodpovedať tomu, čo je napísané, a byť relevantné. Opäť, ak je produkt pravidelne aktualizovaný, bude ťažké sledovať všetkých.
Dĺžka textu. Vyhnite sa príliš dlhým článkom. Rozdeľte ich na časti a ak to nie je možné, pridajte obsah s kotviacimi odkazmi na začiatok článku. Jednoduchý spôsob, ako urobiť článok vizuálne kratším, je skryť technické detaily potrebné pre úzky okruh čitateľov pod spoiler.
formáty. Skombinujte vo svojich článkoch niekoľko formátov: text, video a obrázky. Tým sa zlepší vnímanie.
Nesnažte sa zakryť problémy krásnym rozložením. Úprimne povedané, sami sme dúfali, že „obal“ zachráni zastaranú dokumentáciu - nevyšlo to. Texty obsahovali toľko vizuálneho šumu a zbytočných detailov, že predpisy a nový dizajn boli bezmocné.
Veľa z vyššie uvedeného bude určené platformou, ktorú používate na dokumentáciu. Máme napríklad Confluence. Musel som sa s ním tiež pohrať. Ak máte záujem, prečítajte si príbeh nášho webového vývojára: .
Kde sa začať zlepšovať a ako prežiť
Ak je vaša dokumentácia taká rozsiahla ako dokumentácia ISP a neviete, kde začať, začnite s najväčšími problémami. Klienti nerozumejú dokumentu - vylepšovať texty, robiť predpisy, školiť pisateľov. Dokumentácia je zastaraná – postarajte sa o interné procesy. Začnite s najpopulárnejšími článkami o najobľúbenejších produktoch: požiadajte o podporu, pozrite sa na analýzu stránok a dopyty vo vyhľadávačoch.
Hneď si povedzme – nebude to ľahké. A je nepravdepodobné, že bude fungovať rýchlo. Ibaže by ste práve začínali a nerobili hneď správnu vec. Jedna vec, ktorú vieme určite je, že sa to časom zlepší. Ale proces sa nikdy neskončí :-).
Zdroj: hab.com