Kasutajadokumendatsioon: mis teeb selle halbaks ja kuidas seda parandada

Tarkvarade dokumentatsioon on lihtsalt artiklite kogum. Kuid isegi need võivad vihastada. Esiteks otsid sa pikka aega vajalikku juhendit. Siis püüad aru saada arusaamatust tekstist. Teed nii, nagu on kirjutatud, aga probleem ei lahene. Otsid teise artikli, oled närvis... Tunni aja pärast viskad kõik kõrvale ja lahkud. Nii töötab halb dokumentatsioon. Mis teeb selle selliseks ja kuidas seda parandada – loe allpool.

Meie vanas dokumentatsioonis oli palju puuduseid. Peaaegu aasta oleme seda ümber töötanud, et eespool kirjeldatud stsenaarium ei puudutaks meie kliente. Vaata, kuidas oli ja kuidas on.

Probleem 1. Arusaamatud, halvasti kirjutatud artiklid

Kui dokumentatsioonis ei saa aru, mis mõtet sel on? Kuid keegi ei kirjuta arusaamatuid artikleid spetsiaalselt. Need tekivad, kui autor ei mõtle publikule ja eesmärgile, valab vett ning ei kontrolli teksti vigade osas.

• Publik. Enne artikli kirjutamist tuleks mõelda lugeja ettevalmistustasemele. On mõistlik, et algaja artiklis ei tohi jäetud olla algtegevusi ja tehnilised terminid jäävad seletamatuks, samas kui harva kasutatava funktsiooni artiklis, mis on vajalik ainult professionaalidele, tuleks sõna PHP tähendust põhjalikult seletada.
• Eesmärk. Veel üks asi, millele on parem mõelda ette. Autor peab seadma selge eesmärgi, määratlema artikli kasuliku tegevuse, otsustama, mida lugeja peale selle lugemist teeb. Kui seda ei tehta, saab tulemuseks kirjutamine kirjutamise pärast.
• Vesi ja vead. Liigne teave ja bürokraatlikud väljendid, vead ja trükivead häirivad arusaamist. Isegi kui lugeja ei ole grammatikapolitseinik, võib tekstis räpasus teda tõepoolest peletada.

Arvesse võttes ülaltoodud näpunäiteid, muutuvad artiklid arusaadavamaks – garanteeritud. Et veel parem välja tulla, kasuta meie 50 küsimust tehnilise dokumentatsiooni kallal töötamisel.

Probleem 2. Artiklid ei vasta kõigile küsimustele

On halb, kui dokumentatsioon ei järgi arendust, ei vasta tegelikele küsimustele, vead jäävad aastaid parandamata. Need on probleemid, mis ei ole niivõrd autori, kuivõrd ettevõtte siseste protsesside probleem.

Dokumentatsioon ei järgi arendust

Funktsioon on juba välja antud, turundus plaanib selle kajastamise, ja selgub, et uut artiklit või tõlget dokumentatsioonis ikka veel ei ole. Meil on pidanud seetõttu isegi väljalaskmise edasi lükkama. Võib nii palju kui soovid paluda kõigil õigel ajal ülesanne tehnilistele kirjutajatele edastada, kuid see ei toimi. Kui protsessi ei automatiseerita, kordub olukord aina uuesti.

Oleme teinud muudatusi YouTrackis. Ülesanne kirjutada artikkel uue funktsiooni kohta langeb tehnilise kirjutaja peale samal hetkel, kui võimalusi alustatakse testima. Sellega samal ajal saab sellest teada ka turundus, et valmistuda reklaamimiseks. Teavitused tulevad ka ettevõtte sõnumiteenusesse Mattermost, nii et arendajate uudiseid on lihtsalt võimatu märkamata jätta.

Dokumentatsioon ei kajasta kasutajate soove

Oleme harjunud töötama nii: funktsioon on välja antud, me räägime sellest. Kirjeldame, kuidas see sisse ja välja lülitada, teha õrnu seadistusi. Aga mis siis, kui klient kasutab meie tarkvara viisil, nagu me ei oletanud? Või tekivad tal vead, millest me ei mõelnud?

Et dokumentatsioon oleks võimalikult täielik, soovitame analüüsida klientide toetuse päringuid, teemasid foorumites, otsingumootorite päringuid. Kõige populaarsemaid teemasid tuleks edastada tehnilistele kirjutajatele, et nad täiendaksid olemasolevaid artikleid või kirjutaksid uusi.

Dokumentatsioon ei arene

Raske on kohe ideaali saavutada, vigu ikkagi tuleb. Võib loota klientide tagasiside peale, aga tõenäoliselt ei hakka nad teatama iga trükivea, ebatäpsuse, segase või leidmata artikli kohta. Lisaks klientidele loevad dokumentatsiooni ka töötajad, seega näevad nad samu vigu. Seda saab kasutada! Peab lihtsalt looma tingimused, kus probleemidest on lihtne teatada.

Meil on siseportaalis grupp, kuhu töötajad jätavad märkusi, ettepanekuid ja ideid dokumentatsiooni kohta. Kas toetuseks on vajalik artikkel, aga seda ei ole? Testija märkas ebatäpsust? Partner kaebas arenduse manageritele vigade üle? Kõik sellised asjad sinna gruppi! Tehnilised kirjutajad parandavad midagi kohe, kannavad midagi YouTracki, midagi võtavad arutlusele. Et teema ei jääks unustatud, tuletame vahetevahel meelde grupi olemasolu ja tagasiside tähtsust.

Probleem 3. Vajalikku artiklit on pikka aega keeruline leida

Artikkel, mida ei leia, pole parem kui artikkel, mida ei eksisteeri. Hea dokumentatsiooni moto peaks olema lause "Lihtne otsida, lihtne leida". Kuidas seda saavutada?

Korrastada struktuur ja määrata teema valimise põhimõtted. Struktuur peab olema võimalikult läbipaistev, et lugeja ei mõtleks "Kus ma selle artikli leian?". Kui kokku võtta, siis on kaks lähenemist: liidese poolest ja ülesannete poolest.

1. Liidese poolest. Sisu dubleerib paneeli jaotusi. Nii oli vanas ISPsystemi dokumentatsioonis.
2. Ülesannete poolest. Artiklite ja jaotuste pealkirjad kajastavad kasutajate ülesandeid; pealkirjades on peaaegu alati tegusõnad ja vastused küsimusele "kuidas teha". Praegu liigume sellise formaadi suunas.

Kuidas iganes lähenete, veenduge, et teema vastab kasutajate päringutele ja on käsitletud nii, et kasutaja saaks oma küsimisele kindlasti vastuse.

Keskne otsingu loomine. Ideaalmaailmas peaks otsing toimima isegi siis, kui eksite kirjapildis või olete keelega valesti. Meie Confluence'i otsing ei saa praegu sellega kiidelda. Kui teil on palju tooteid ja dokumentatsioon on üldine, kohandage otsingut vastavalt sellele leheküljele, kus kasutaja viibib. Meie puhul töötab otsing esilehel kõigi toodete peal, kuid kui olete juba konkreetse jaotuse sees, siis ainult sealsete artiklite jaoks.

Lisada sisu ja "leivajalad". Hea on, kui iga lehekülje peal on menüü ja leivajalad — kasutaja tee praegusele leheküljele, võimalusega tagasi minna igale tasemele. Vanas ISPsystemi dokumentatsioonis pidi artiklist väljumiseks minema sisu juurde. See oli ebamugav, seega oleme seda uues parandatud.

Seada lingid tootes. Kui inimesed tulevad korduvalt toele sama küsimusega, on mõistlik lisada liidesesse vihje selle lahendusele. Kui teil on andmeid või arusaam, millal kasutaja probleemiga silmitsi seisab, saate teda ka teadaande kaudu teavitada. Niimoodi näitate hoolivust ja vähendate toe koormust.

Paremal hüpikaknas link artiklile DNSSEC-i seadistamise kohta ISPmanageri domeenihalduse jaotuses

Seada ristsidemed dokumentatsioonisOmavahel seotud artiklid peaksid olema "linkitud". Kui artiklid esindavad järjestust, lisage kindlasti iga teksti lõppu nooled edasi ja tagasi.

Tõenäoliselt otsib inimene esmalt vastust oma küsimusele mitte teie juurest, vaid otsingumootorist. On kurb, kui tehnilistel põhjustel seal dokumentatsiooni linke ei ole. Seega hoolitsege otsingumootori optimeerimise eest.

Probleem 4. Aegunud kujundus häirib arusaamist

Lisaks halvale tekstile võib dokumentatsiooni rikkuda ka kujundus. Inimesed on harjunud lugema hästi vormindatud materjale. Blogid, sotsiaalmeedia, meedia — kõik sisu esitatakse mitte ainult ilusalt, vaid ka lugemiseks mugavalt ja silmadele meeldivalt. Seetõttu on lihtne mõista inimese valu, kes näeb teksti nagu alloleval ekraanipildil.

Selles artiklis on ekraanipilte ja esiletõstmisi nii palju, et need ei aita, vaid pigem häirivad arusaamist (pilt on klikkitav)

Ei tohiks teha dokumentatsioonist pikalt loetavat teksti, kuid põhireeglid tuleks arvesse võtta.

Kujundus. Määrake peateksti laius, font, suurus, pealkirjad ja vahed. Tõmmake disainer appi, ja et tööd vastu võtta või ise toime tulla, lugege Artyom Gorbunovi raamatut "Tüüfografika ja kujundus". Selles on esitatud vaid üks vaatenurk kujundusele, kuid sellest piisab.

Esiletõstmised. Määrake, mis nõuab tekstis aktsente. Tavaliselt on need teed liideses, nupud, koodilõikud, konfiguratsioonifailid, plokid "Pöörake tähelepanu". Määrake, millised on nende elementide esiletõstmised ja fikseerige see määrustes. Pidage meeles, et mida vähem esiletõstmisi, seda parem. Kui neid on palju, on tekst "mürarikka". Müra tekitavad isegi jutumärgid, kui neid kasutatakse liiga sageli.

Kuvandid. Leppige meeskonnaga kokku, millal on vajalikud ekraanipildid. Iga sammu illustreerimine ei ole kindlasti vajalik. Suur hulk ekraanipilte, sealhulgas eraldi nuppe, häirib arusaamist ja rikub kujundust. Määrake suurus, samuti esiletõstmiste ja ekraanipiltide pealkirjade formaat ning fikseerige see määrustes. Pidage meeles, et illustreerimised peaksid alati vastama kirjutatule ja olema asjakohased. Jällegi, kui toode uuendatakse regulaarselt, on igaühe jälgimine keeruline.

Teksti pikkus. Väldi liiga pikki artikleid. Jagada neid osadeks, kui see on võimatu, lisa artikli algusesse sisu koos ankrulinkidega. Lihtne viis artikli visuaalse lühenemise saavutamiseks on tehniliste detailide peitmine, mis on vajalikud kitsale lugejaskonnale, spoilerisse.

Formaadid. Kombineeri artiklites mitut formaati: tekst, video ja pildid. See parendab arusaamist.

Ära ürita probleeme ilusa vormistusega varjata. Ausalt öeldes lootsime ka, et „ümbrus“ päästab vananenud dokumentatsiooni - see ei õnnestunud. Tekstides oli nii palju visuaalset müra ja liigseid detaile, et regulatiiv ja uus kujundus olid jõuetud.

Palju sellest, mis eespool on kirjeldatud, sõltub platvormist, mida kasutad dokumentatsiooni jaoks. Meil on näiteks see Confluence. Sellega tuli ka vaeva näha. Kui huvitab, loe meie veebiarendaja lugu: Confluence avaliku teadmistebaasi jaoks: muudame kujundust ja seadistame keelesegmente.

Kust alustada parendusi ja kuidas ellu jääda

Kui sinu dokumentatsioon on sama ulatuslik kui ISPsystemi oma, ja sa ei tea, millest alustada, alusta kõige tõsisemaid probleeme. Klientidel on dokumentatsioon arusaamatu - tee tekstid paremaks, loo regulatiivsed dokumendid, koolita kirjutajaid. Dokumentatsioon on aegunud - tegele sisemiste protsessidega. Alusta kõige populaarsematest artiklitest kõige nõudlikumate toodete kohta: küsi tosupportilt, vaata veebianalüütikat ja otsingupäringute tulemusi.

Ütleme kohe - lihtne ei ole. Ja kiiresti ka kindlasti mitte. Kui just alustad ja teed kohe õigesti. Ühte me teame kindlalt - aja jooksul läheb paremaks. Kuid protsess ei lõpe kunagi :-).

Allikas: habr.com