Tarkvara dokumentatsioon on vaid artiklite kogum. Kuid isegi need võivad teid hulluks ajada. Esiteks kulutate pikka aega vajalike juhiste otsimisele. Siis saate hämarast tekstist aru. Teete nii nagu kirjutatud, kuid probleem ei lahene. Otsid teist artiklit, lähed närvi... Tund hiljem annad kõiges alla ja lahkud. Nii toimib halb dokumentatsioon. Mis selle selliseks teeb ja kuidas seda parandada – loe lõike alt.
Meie vanas dokumentatsioonis oli palju puudujääke. Oleme seda juba pea aasta ümber töötanud, et eelpool kirjeldatud stsenaarium meie kliente ei puudutaks. Vaata, и .
Probleem 1: ebaselged, halvasti kirjutatud artiklid
Kui dokumentatsioonist on võimatu aru saada, siis mis mõte sellel on? Kuid keegi ei kirjuta meelega arusaamatuid artikleid. Need juhtuvad siis, kui autor ei mõtle publikule ja eesmärgile, valab vett ega kontrolli tekstis vigu.
- Publik. Enne artikli kirjutamist peate mõtlema lugeja ettevalmistuse tasemele. On loogiline, et algajale mõeldud artiklis ei tohiks te põhisamme vahele jätta ja tehnilisi termineid ilma selgituseta jätta, kuid artiklis, mis käsitleb haruldast funktsiooni, mida vajavad ainult professionaalid, peaksite selgitama sõna PHP tähendust.
- Eesmärk. Veel üks asi, millele eelnevalt mõelda. Autor peab seadma selge eesmärgi, määrama artikli kasuliku mõju ja otsustama, mida lugeja pärast selle lugemist ette võtab. Kui seda ei tehta, saate kirjelduse huvides kirjelduse.
- Vesi ja putukad. Ebavajalikku infot ja bürokraatiat on palju, vead ja kirjavead segavad tajumist. Isegi kui lugeja pole grammatikanats, võib hoolimatus tekstis ta välja lülitada.
Võtke arvesse ülaltoodud näpunäiteid ja artiklid muutuvad selgemaks - garanteeritud. Selle veelgi paremaks muutmiseks kasutage meie .
Probleem 2. Artiklid ei vasta kõigile küsimustele
Halb on see, kui dokumentatsioon ei käi arenguga kaasas, ei vasta tegelikele küsimustele ja selles sisalduvaid vigu ei parandata aastaid. Need ei ole mitte niivõrd autori, vaid ettevõttesisese protsesside korralduse probleemid.
Dokumentatsioon ei käi arenguga kaasas
Funktsioon on juba välja antud, turundus plaanib seda katta ja siis selgub, et uut artiklit või tõlget pole ikka veel dokumentatsioonis. Selle tõttu pidime isegi avaldamise edasi lükkama. Võite paluda kõigil anda tehnilistele kirjutajatele ülesandeid õigel ajal üle nii palju kui soovite, kuid see ei tööta. Kui protsess pole automatiseeritud, kordub olukord.
Oleme YouTrackis teinud muudatusi. Uue funktsiooni kohta artikli kirjutamise ülesanne langeb tehnilisele kirjutajale samal hetkel, kui funktsiooni hakatakse testima. Seejärel õpib turundus seda tundma, et valmistuda edutamiseks. Märguanded tulevad ka Mattermost ettevõtte messengerisse, nii et arendajate uudistest on lihtsalt võimatu ilma jääda.
Dokumentatsioon ei kajasta kasutaja taotlusi
Oleme harjunud töötama nii: funktsioon tuli välja, me rääkisime sellest. Kirjeldasime, kuidas seda sisse, välja lülitada ja peensätteid teha. Aga mis siis, kui klient kasutab meie tarkvara viisil, mida me ei oodanud? Või on sellel vigu, millele me ei mõelnud?
Tagamaks, et dokumentatsioon oleks võimalikult täielik, soovitame analüüsida tugitaotlusi, temaatiliste foorumite küsimusi ja päringuid otsingumootorites. Kõige populaarsemad teemad kantakse üle tehnilistele kirjutajatele, et nad saaksid olemasolevaid artikleid täiendada või uusi kirjutada.
Dokumentatsiooni ei täiustata
Seda on raske kohe täiuslikult teha, ikka tuleb ette vigu. Võite loota klientide tagasisidet, kuid on ebatõenäoline, et nad teavitavad igast kirjaveast, ebatäpsusest, arusaamatust või alusetust artiklist. Lisaks klientidele loevad dokumentatsiooni töötajad, mis tähendab, et nad näevad samu vigu. Seda saab kasutada! Peate lihtsalt looma tingimused, mille korral on probleemist lihtne teatada.
Meil on siseportaalis grupp, kuhu töötajad jätavad dokumentatsiooni kohta kommentaare, ettepanekuid ja ideid. Kas tugi vajab artiklit, kuid seda pole olemas? Kas testija märkas ebatäpsust? Kas partner on kaebanud arendusjuhtidele vigade üle? Kõik selles grupis! Tehnilised kirjutajad parandavad mõned asjad kohe ära, kannavad mõned asjad üle YouTracki ja annavad teistele veidi mõtlemisaega. Teema vaibumise vältimiseks tuletame aeg-ajalt meelde grupi olemasolu ja tagasiside olulisust.
Probleem 3. Õige artikli leidmine võtab kaua aega.
Artikkel, mida ei leita, pole parem kui artikkel, mida ei leita. Hea dokumentatsiooni moto peaks olema "Lihtne otsida, lihtne leida". Kuidas seda saavutada?
Korraldage struktuur ja määrake teemade valiku põhimõte. Struktuur peaks olema võimalikult läbipaistev, et lugeja ei mõtleks: "Kust ma selle artikli leian?" Kokkuvõtteks võib öelda, et on kaks lähenemist: liidesest ja ülesannetest.
- Liidesest. Sisu dubleerib paneeli sektsioone. Nii oli see vanas ISP-süsteemi dokumentatsioonis.
- Ülesannetest. Artiklite ja jaotiste pealkirjad kajastavad kasutajate ülesandeid; Pealkirjad sisaldavad peaaegu alati tegusõnu ja vastuseid küsimusele "kuidas teha". Nüüd liigume selle vormingu juurde.
Ükskõik millise lähenemisviisi valite, veenduge, et teema oleks kasutajate otsitava jaoks asjakohane ja seda käsitletakse viisil, mis käsitleb konkreetselt kasutaja küsimust.
Seadistage tsentraliseeritud otsing. Ideaalses maailmas peaks otsing toimima isegi siis, kui kirjutate õigekirja või eksite keelega. Meie senised otsingud Confluence'is ei saa meid sellega rahuldada. Kui teil on palju tooteid ja dokumentatsioon on üldine, kohandage otsing vastavalt lehele, millel kasutaja on. Meie puhul töötab pealehel olev otsing kõikide toodete puhul ja kui olete juba konkreetses jaotises, siis ainult selles olevate artiklite puhul.
Lisa sisu ja riivsai. On hea, kui igal lehel on menüü ja leivad – kasutaja tee praegusele lehele koos võimalusega naasta mis tahes tasemele. Vanas ISP-süsteemi dokumentatsioonis pidite sisu juurde pääsemiseks artiklist väljuma. See oli ebamugav, nii et parandasime selle uues.
Asetage lingid tootesse. Kui inimesed tulevad ikka ja jälle toetama sama küsimusega, on mõttekas lisada liidesele selle lahendusega vihje. Kui teil on andmeid või teavet selle kohta, millal kasutajal on probleem, saate teda teavitada ka meililistiga. Näidake neile muret ja võtke koorem toetusest maha.
Hüpikaknas paremal on link artiklile DNSSECi seadistamise kohta ISPmanageri domeenihalduse jaotises
Seadistage dokumentatsioonis ristviited. Artiklid, mis on omavahel seotud, peaksid olema "lingitud". Kui artiklid on järjestikused, lisage kindlasti iga teksti lõppu edasi- ja tagasinooled.
Tõenäoliselt läheb inimene kõigepealt oma küsimusele vastust otsima mitte teile, vaid otsingumootorisse. Kahju, kui tehnilistel põhjustel pole dokumentatsiooni linke. Nii et hoolitsege otsingumootori optimeerimise eest.
Ülesanne 4. Vananenud paigutus segab tajumist
Lisaks halbadele tekstidele võib dokumentatsiooni rikkuda disain. Inimesed on harjunud lugema hästi kirjutatud materjale. Blogid, sotsiaalvõrgustikud, meedia – kogu sisu pole mitte ainult ilus, vaid ka lihtsalt loetav ja silmale meeldiv. Seetõttu saate hõlpsalt aru saada inimese valust, kes näeb teksti nagu alloleval ekraanipildil.
Selles artiklis on nii palju ekraanipilte ja esiletõstmisi, et need ei aita, vaid ainult segavad tajumist (pilt on klõpsatav)
Te ei tohiks teha dokumentatsioonist pikka lugemist koos hunniku efektidega, kuid peate arvestama põhireeglitega.
Paigutus. Määrake kehateksti laius, font, suurus, pealkirjad ja polsterdus. Palgake disainer ja töö vastuvõtmiseks või ise tegemiseks lugege Artjom Gorbunovi raamatut “Tüpograafia ja paigutus”. See kujutab ainult ühte vaadet paigutusest, kuid see on täiesti piisav.
Eraldised. Määrake, mis vajab tekstis rõhutamist. Tavaliselt on see tee liideses, nuppudes, koodisisestes, konfiguratsioonifailides ja plokkides "Palun tähele". Tehke kindlaks, millised on nende elementide jaotused, ja registreerige need määrustes. Pidage meeles, et mida vähem tühjendust, seda parem. Kui neid on palju, on tekst lärmakas. Isegi jutumärgid tekitavad müra, kui neid liiga sageli kasutatakse.
Screenshots. Leppige meeskonnaga kokku, millistel juhtudel on ekraanipilte vaja. Kindlasti pole vaja iga sammu illustreerida. Suur hulk ekraanipilte, sh. eraldi nupud, segavad taju, rikuvad paigutust. Määrake ekraanipiltide esiletõstude ja allkirjade suurus, vorming ja märkige need eeskirjadesse. Pidage meeles, et illustratsioonid peaksid alati vastama kirjutatule ja olema asjakohased. Jällegi, kui toodet uuendatakse regulaarselt, on raske kõigiga kursis hoida.
Teksti pikkus. Vältige liiga pikki artikleid. Jagage need osadeks ja kui see pole võimalik, lisage ankurlinkidega sisu artikli algusesse. Lihtne viis artiklit visuaalselt lühemaks muuta on peita kitsale lugejaskonnale vajalikud tehnilised detailid spoileri alla.
Formaadid. Kombineerige oma artiklites mitut vormingut: tekst, video ja pildid. See parandab taju.
Ärge püüdke varjata probleeme kauni paigutusega. Ausalt öeldes lootsime ise, et "ümbris" päästab vananenud dokumentatsiooni - see ei õnnestunud. Tekstid sisaldasid nii palju visuaalset müra ja tarbetuid detaile, et määrused ja uus kujundus olid jõuetud.
Suure osa ülaltoodust määrab platvorm, mida kasutate dokumenteerimiseks. Näiteks on meil Confluence. Ma pidin ka temaga nokitsema. Huvi korral lugege meie veebiarendaja lugu: .
Millest alustada parandamist ja kuidas ellu jääda
Kui teie dokumentatsioon on sama mahukas kui ISPsystem ja te ei tea, kust alustada, alustage suurimatest probleemidest. Kliendid ei saa dokumendist aru – parandage tekste, koostage määrusi, koolitage kirjutajaid. Dokumentatsioon on aegunud – hoolitsege sisemiste protsesside eest. Alustage kõige populaarsemate artiklitega kõige populaarsemate toodete kohta: küsige tuge, vaadake saidi analüüse ja päringuid otsingumootorites.
Ütleme kohe – see ei saa olema lihtne. Ja tõenäoliselt ei tööta see kiiresti. Kui te just ei alusta ja tee kohe õiget asja. Üks asi, mida me kindlalt teame, on see, et see muutub aja jooksul paremaks. Kuid protsess ei lõpe kunagi :-).
Allikas: www.habr.com