Programska dokumentacija je le niz člankov. Toda tudi oni te lahko spravijo ob pamet. Prvič, dolgo časa iščete potrebna navodila. Potem razumete nejasno besedilo. Delaš kot je napisano, a problem ni rešen. Iščeš drug artikel, postaneš živčen ... Uro kasneje obupaš nad vsem in greš. Tako deluje slaba dokumentacija. Zakaj je tako in kako to popraviti - preberite pod rezom.
V naši stari dokumentaciji je bilo veliko pomanjkljivosti. Že skoraj leto dni ga predelujemo tako, da zgoraj opisani scenarij ne vpliva na naše stranke. Poglej, и .
Problem 1: Nejasni, slabo napisani članki
Če je dokumentacije nemogoče razumeti, kakšen smisel ima to? Ampak nihče ne piše nerazumljivih člankov namenoma. Zgodijo se, ko avtor ne razmišlja o občinstvu in namenu, nalije vodo in ne preveri besedila za napake.
- Občinstvo. Preden napišete članek, morate razmisliti o stopnji pripravljenosti bralca. Logično je, da v članku za začetnika ne smete preskočiti osnovnih korakov in pustiti tehničnih izrazov brez razlage, v članku o redki funkciji, ki jo potrebujejo le profesionalci, pa morate pojasniti pomen besede PHP.
- Cilj. Še ena stvar, o kateri morate razmišljati vnaprej. Avtor si mora postaviti jasen cilj, določiti koristen učinek članka in se odločiti, kaj bo bralec naredil po branju. Če tega ne storite, boste na koncu dobili opis zaradi opisa.
- Voda in hrošči. Veliko je nepotrebnih informacij in birokracije, napake in tipkarske napake motijo zaznavanje. Tudi če bralec ni slovnični nacist, ga lahko neprevidnost v besedilu odvrne.
Upoštevajte zgornje nasvete in članki bodo postali jasnejši - zagotovljeno. Da bo še bolje, uporabite naše .
Problem 2. Članki ne odgovarjajo na vsa vprašanja
Hudo je, če dokumentacija ne sledi razvoju, ne odgovarja na prava vprašanja in napake v njej niso odpravljene leta. To niso toliko problemi avtorja, ampak težave organizacije procesov v podjetju.
Dokumentacija ne dohaja razvoja
Funkcija je že v izdaji, trženje jo namerava pokriti, nato pa se izkaže, da novega članka ali prevoda še vedno ni v dokumentaciji. Zaradi tega smo morali izid celo preložiti. Od vseh lahko zahtevate, da naloge predajajo tehničnim piscem pravočasno, kolikor želite, vendar ne bo šlo. Če postopek ni avtomatiziran, se bo situacija ponovila.
YouTrack smo spremenili. Naloga pisanja članka o novi funkciji pade na tehničnega pisca v istem trenutku, ko se funkcija začne testirati. Nato marketing izve o tem, da se pripravi na promocijo. Obvestila prihajajo tudi v korporativni messenger Mattermost, zato je enostavno nemogoče zamuditi novice razvijalcev.
Dokumentacija ne odraža zahtev uporabnikov
Navajeni smo delati tako: pojavila se je funkcija, o njej smo govorili. Opisali smo, kako ga vklopiti, izklopiti in narediti natančne nastavitve. Kaj pa, če stranka uporablja našo programsko opremo na način, ki ga nismo pričakovali? Ali pa ima napake, na katere nismo pomislili?
Da bi bila dokumentacija čim bolj popolna, priporočamo analizo zahtevkov za podporo, vprašanj na tematskih forumih in poizvedb v iskalnikih. Najbolj priljubljene teme bodo prenesene k tehničnim piscem, da bodo lahko dopolnili obstoječe članke ali napisali nove.
Dokumentacija se ne izboljšuje
Težko je takoj narediti popolno, še vedno bodo napake. Lahko se nadejate povratnih informacij strank, vendar je malo verjetno, da bodo poročale o vsaki tipkarski napaki, netočnosti, nerazumljivem ali nenajdenem članku. Dokumentacijo poleg strank berejo tudi zaposleni, kar pomeni, da vidijo iste napake. To se da uporabiti! Samo ustvariti morate pogoje, v katerih bo težavo enostavno prijaviti.
Na internem portalu imamo skupino, kjer zaposleni dajejo pripombe, predloge in ideje na dokumentacijo. Ali podpora potrebuje članek, ki pa ne obstaja? Ali je tester opazil netočnost? Ali se je partner pritožil vodjem razvoja zaradi napak? Vsi v tej skupini! Tehnični pisci nekatere stvari popravijo takoj, nekatere prenesejo na YouTrack, drugim pa dajo nekaj časa za razmislek. Da tema ne bo zamrla, vas občasno spomnimo na obstoj skupine in pomen povratnih informacij.
Težava 3. Traja dolgo časa, da najdemo pravi izdelek.
Članek, ki ga ni mogoče najti, ni nič boljši od članka, ki ga ni mogoče najti. Moto dobre dokumentacije bi moral biti "Enostaven za iskanje, enostavno najti." Kako to doseči?
Organizirajte strukturo in določite načelo izbire tem. Struktura mora biti čim bolj pregledna, da bralec ne pomisli: "Kje lahko najdem ta članek?" Če povzamemo, obstajata dva pristopa: iz vmesnika in iz nalog.
- Iz vmesnika. Vsebina podvaja razdelke plošče. Tako je bilo v stari dokumentaciji ISPsystem.
- Od nalog. Naslovi člankov in rubrik odražajo naloge uporabnikov; Naslovi skoraj vedno vsebujejo glagole in odgovore na vprašanje "kako". Zdaj prehajamo na to obliko.
Ne glede na pristop, ki ga izberete, se prepričajte, da je tema ustrezna glede na to, kar uporabniki iščejo, in je zajeta na način, ki natančno obravnava uporabnikovo vprašanje.
Nastavite centralizirano iskanje. V idealnem svetu bi moralo iskanje delovati tudi, če napačno črkujete ali se zmotite v jeziku. Naše dosedanje iskanje v Confluenceu nas s tem ne more zadovoljiti. Če imate veliko izdelkov in je dokumentacija splošna, prilagodite iskanje strani, na kateri je uporabnik. V našem primeru iskanje na glavni strani deluje za vse izdelke, če ste že v določeni rubriki, pa samo za artikle v njej.
Dodajte vsebino in drobtinice. Dobro je, če ima vsaka stran meni in drobtinice - pot uporabnika do trenutne strani z možnostjo vrnitve na katero koli raven. V stari dokumentaciji ISPsystem ste morali zapustiti članek, da ste prišli do vsebine. Bilo je neprijetno, zato smo to popravili v novem.
Postavite povezave v izdelek. Če ljudje znova in znova pridejo na podporo z istim vprašanjem, je smiselno vmesniku dodati namig z njegovo rešitvijo. Če imate podatke ali vpogled v to, kdaj ima uporabnik težave, ga lahko o tem obvestite tudi z mailing listo. Pokažite jim skrb in odstranite breme podpore.
Na desni v pojavnem oknu je povezava do članka o nastavitvi DNSSEC v razdelku za upravljanje domene v ISPmanagerju
Nastavite navzkrižne sklice znotraj dokumentacije. Članki, ki so med seboj povezani, naj bodo »povezani«. Če so članki zaporedni, ne pozabite dodati puščic naprej in nazaj na koncu vsakega besedila.
Najverjetneje bo oseba najprej iskala odgovor na svoje vprašanje ne k vam, ampak k iskalniku. Škoda, če tam iz tehničnih razlogov ni povezav do dokumentacije. Poskrbite torej za optimizacijo iskalnikov.
Problem 4. Zastarela postavitev moti zaznavanje
Poleg slabih besedil lahko dokumentacijo pokvari dizajn. Ljudje smo navajeni brati dobro napisana gradiva. Blogi, socialna omrežja, mediji - vsa vsebina ni le lepa, ampak tudi berljiva in prijetna za oko. Zato lahko zlahka razumete bolečino osebe, ki vidi besedilo, kot je na spodnjem posnetku zaslona.
V tem članku je toliko posnetkov zaslona in poudarkov, da ne pomagajo, ampak samo motijo zaznavo (sliko je mogoče klikniti)
Iz dokumentacije ne smete delati longreada s kupom učinkov, vendar morate upoštevati osnovna pravila.
Postavitev. Določite širino besedila, pisavo, velikost, naslove in odmik. Najemite oblikovalca in če želite delo sprejeti ali opraviti sami, preberite knjigo Artjoma Gorbunova »Tipografija in postavitev«. Predstavlja le en pogled na postavitev, ki pa povsem zadostuje.
Izpustitev. Ugotovite, kaj v besedilu zahteva poudarek. Običajno je to pot v vmesniku, gumbi, vstavki kode, konfiguracijske datoteke, bloki »Upoštevajte«. Določite, kakšne bodo razporeditve teh elementov in jih zapišite v predpise. Ne pozabite, da manj je izpustov, bolje je. Ko jih je veliko, je besedilo hrupno. Tudi narekovaji povzročajo hrup, če se uporabljajo prepogosto.
Galerija slik:. Dogovorite se z ekipo, v katerih primerih so potrebni posnetki zaslona. Vsekakor ni treba ilustrirati vsakega koraka. Veliko število posnetkov zaslona, vklj. ločeni gumbi, motijo zaznavanje, pokvarijo postavitev. Določite velikost, pa tudi obliko poudarkov in podpisov na posnetkih zaslona ter jih zabeležite v pravilniku. Ne pozabite, da morajo ilustracije vedno ustrezati napisanemu in biti ustrezne. Še enkrat, če se izdelek redno posodablja, bo težko slediti vsem.
Dolžina besedila. Izogibajte se predolgim člankom. Razdelite jih na dele, in če to ni mogoče, dodajte vsebino s sidrnimi povezavami na začetek članka. Preprost način vizualno skrajšati članek je, da pod spojler skrijete tehnične podrobnosti, ki jih potrebuje ozek krog bralcev.
Oblike. V svojih člankih združite več formatov: besedilo, video in slike. To bo izboljšalo zaznavanje.
Ne poskušajte prikriti težav s čudovito postavitvijo. Iskreno povedano, sami smo upali, da bo "ovitek" rešil zastarelo dokumentacijo - ni se izšlo. Besedila so vsebovala toliko vizualnega šuma in nepotrebnih podrobnosti, da so bili predpisi in nova zasnova nemočni.
Večino zgoraj navedenega bo določila platforma, ki jo uporabljate za dokumentacijo. Na primer, imamo Confluence. Tudi jaz sem se moral poigrati z njim. Če vas zanima, preberite zgodbo našega spletnega razvijalca: .
Kje se začeti izboljševati in kako preživeti
Če je vaša dokumentacija tako obsežna kot ISPsystem in ne veste, kje začeti, začnite z največjimi težavami. Stranke ne razumejo dokumenta - izboljšajte besedila, naredite predpise, učite pisce. Dokumentacija je zastarela – poskrbite za notranje procese. Začnite z najbolj priljubljenimi članki o najbolj priljubljenih izdelkih: vprašajte podporo, poglejte analitiko spletnega mesta in poizvedbe v iskalnikih.
Recimo takoj – ne bo lahko. In tudi verjetno ne bo delovalo hitro. Razen če ste šele na začetku in takoj naredite pravo stvar. Zagotovo vemo, da bo sčasoma bolje. Toda proces se ne bo nikoli končal :-).
Vir: www.habr.com