ProHoster > Blogs > interneta ziņas > Lietotāja dokumentācija: kas padara to par sliktu un kā to labot

Lietotāja dokumentācija: kas padara to par sliktu un kā to labot

Lietotāja dokumentācija: kas padara to par sliktu un kā to labot

ProgrammatÅ«ras dokumentācija ir tikai rakstu kopums. Bet pat viņi var padarÄ«t jÅ«s traku. Pirmkārt, jÅ«s pavadāt ilgu laiku, meklējot nepiecieÅ”amos norādÄ«jumus. Tad jÅ«s saprotat neskaidro tekstu. JÅ«s darāt, kā rakstÄ«ts, bet problēma nav atrisināta. Tu meklē citu rakstu, sanervozē...Stundu vēlāk tu padodies visam un aizej. Šādi darbojas slikta dokumentācija. Kas to padara tādu un kā to salabot - lasiet zem griezuma.

MÅ«su vecajā dokumentācijā bija daudz trÅ«kumu. Jau gandrÄ«z gadu esam to pārstrādājuÅ”i, lai iepriekÅ” aprakstÄ«tais scenārijs neskartu mÅ«su klientus. Skaties, kā tas bija Šø kā tas notika.

1. problēma: neskaidri, slikti uzrakstīti raksti

Ja dokumentāciju nav iespējams saprast, kāda jēga no tā? Neviens taču tīŔām neraksta nesaprotamus rakstus. Tās notiek, kad autors nedomā par auditoriju un mērÄ·i, lej Å«deni un nepārbauda, ā€‹ā€‹vai tekstā nav kļūdu.

  • MērÄ·auditorija. Pirms raksta rakstu, jums ir jādomā par lasÄ«tāja sagatavotÄ«bas lÄ«meni. LoÄ£iski, ka rakstā iesācējam nevajadzētu izlaist pamatsoļus un atstāt tehniskos terminus bez paskaidrojumiem, bet rakstā par retu funkciju, kas nepiecieÅ”ama tikai profesionāļiem, jāpaskaidro vārda PHP nozÄ«me.
  • mērÄ·is. Vēl viena lieta, kas jāpadomā iepriekÅ”. Autoram ir jāizvirza skaidrs mērÄ·is, jānosaka raksta lietderÄ«gais efekts un jāizlemj, ko lasÄ«tājs darÄ«s pēc tā izlasÄ«Å”anas. Ja tas nav izdarÄ«ts, apraksta labad jÅ«s saņemsit aprakstu.
  • ÅŖdens un kukaiņi. Ir daudz nevajadzÄ«gas informācijas un birokrātijas, kļūdas un drukas kļūdas traucē uztveri. Pat ja lasÄ«tājs nav gramatikas nacists, pavirŔība tekstā var viņu izslēgt.

Apsveriet iepriekÅ” minētos padomus, un raksti kļūs skaidrāki - garantēti. Lai padarÄ«tu to vēl labāku, izmantojiet mÅ«su 50 jautājumi, strādājot pie tehniskās dokumentācijas.

2. problēma. Raksti neatbild uz visiem jautājumiem

Ir slikti, ja dokumentācija neseko attīstībai, neatbild uz reāliem jautājumiem un kļūdas tajā netiek labotas gadiem ilgi. Tās ir ne tik daudz autora, bet gan procesu organizācijas problēmas uzņēmumā.

Dokumentācija neseko attīstībai

Funkcija jau ir izlaista, mārketings plāno to aptvert, un tad izrādās, ka jaunais raksts vai tulkojums joprojām nav dokumentācijā. Å Ä« iemesla dēļ mums pat bija jāatliek izlaiÅ”ana. Varat lÅ«gt ikvienam nodot uzdevumus tehniskajiem rakstniekiem laikā, cik vēlaties, taču tas nedarbosies. Ja process nav automatizēts, situācija atkārtosies.

Mēs esam veikuÅ”i izmaiņas pakalpojumā YouTrack. Uzdevums uzrakstÄ«t rakstu par jaunu lÄ«dzekli ir tehniskajam rakstÄ«tājam tajā paŔā brÄ«dÄ«, kad tiek sākta funkcijas testÄ“Å”ana. Tad mārketings par to uzzina, lai sagatavotos veicināŔanai. Paziņojumi nāk arÄ« uz Mattermost korporatÄ«vo kurjeru, tāpēc vienkārÅ”i nav iespējams palaist garām jaunumus no izstrādātājiem.

Dokumentācija neatspoguļo lietotāju pieprasījumus

Mēs esam pieraduÅ”i strādāt Ŕādi: iznāca funkcija, mēs par to runājām. Mēs aprakstÄ«jām, kā to ieslēgt, izslēgt un veikt precÄ«zus pielāgojumus. Bet ko darÄ«t, ja klients izmanto mÅ«su programmatÅ«ru tā, kā mēs negaidÄ«jām? Vai arÄ« tajā ir kļūdas, par kurām mēs nedomājām?

Lai nodroÅ”inātu, ka dokumentācija ir pēc iespējas pilnÄ«gāka, iesakām analizēt atbalsta pieprasÄ«jumus, jautājumus tematiskajos forumos un vaicājumus meklētājprogrammās. Populārākās tēmas tiks nodotas tehniskajiem rakstÄ«tājiem, lai viņi varētu papildināt esoÅ”os rakstus vai rakstÄ«t jaunus.

Dokumentācija netiek pilnveidota

Ir grÅ«ti to izdarÄ«t perfekti uzreiz, joprojām bÅ«s kļūdas. Var cerēt uz klientu atsauksmēm, taču maz ticams, ka viņi ziņos par katru drukas kļūdu, neprecizitāti, nesaprotamu vai nepamatotu rakstu. Papildus klientiem, darbinieki lasa dokumentāciju, kas nozÄ«mē, ka viņi redz tās paÅ”as kļūdas. Å o var izmantot! Jums vienkārÅ”i jārada apstākļi, kuros bÅ«s viegli ziņot par problēmu.

Mums iekŔējā portālā ir izveidota grupa, kurā darbinieki atstāj komentārus, ieteikumus un idejas par dokumentāciju. Vai atbalstam ir vajadzÄ«gs raksts, bet tā nav? Vai testētājs pamanÄ«ja neprecizitāti? Vai partneris ir sÅ«dzējies attÄ«stÄ«bas vadÄ«tājiem par kļūdām? Visi Å”ajā grupā! Tehniskie rakstnieki dažas lietas izlabo uzreiz, dažas lietas nodod pakalpojumam YouTrack, bet citām dod laiku pārdomām. Lai tēma nerimtu, ik pa laikam atgādinām par grupas esamÄ«bu un atgriezeniskās saites nozÄ«mi.

3. problēma. Lai atrastu pareizo rakstu, nepiecieÅ”ams ilgs laiks.

Raksts, kuru nevar atrast, nav labāks par rakstu, kuru nevar atrast. Labas dokumentācijas devÄ«zei jābÅ«t ā€œViegli meklēt, viegli atrastā€. Kā to panākt?

Sakārtojiet struktÅ«ru un nosakiet tēmu izvēles principu. StruktÅ«rai jābÅ«t pēc iespējas caurspÄ«dÄ«gākai, lai lasÄ«tājs nedomā: "Kur es varu atrast Å”o rakstu?" Rezumējot, ir divas pieejas: no saskarnes un no uzdevumiem.

  1. No saskarnes. Saturs dublē paneļa sadaļas. Tā tas bija vecajā ISP sistēmas dokumentācijā.
  2. No uzdevumiem. Rakstu un sadaļu nosaukumi atspoguļo lietotāju uzdevumus; Nosaukumos gandrÄ«z vienmēr ir ietverti darbÄ«bas vārdi un atbildes uz jautājumu ā€œkā to darÄ«tā€. Tagad mēs pārejam uz Å”o formātu.

NeatkarÄ«gi no izvēlētās pieejas pārliecinieties, vai tēma atbilst lietotāju meklētajam un ir ietverta tādā veidā, kas Ä«paÅ”i attiecas uz lietotāja jautājumu.

Iestatiet centralizētu meklÄ“Å”anu. Ideālā pasaulē meklÄ“Å”anai jādarbojas pat tad, ja esat pareizrakstÄ«bas kļūdas vai pieļaujat kļūdu ar valodu. MÅ«su lÄ«dzÅ”inējie meklējumi Confluence mÅ«s ar to nevar iepriecināt. Ja jums ir daudz produktu un dokumentācija ir vispārÄ«ga, pielāgojiet meklÄ“Å”anu lapai, kurā atrodas lietotājs. MÅ«su gadÄ«jumā meklÄ“Å”ana galvenajā lapā darbojas visiem produktiem, un, ja jau atrodaties konkrētā sadaļā, tad tikai tajā esoÅ”ajiem rakstiem.

Pievienojiet saturu un rÄ«vmaizi. Ir labi, ja katrā lapā ir izvēlne un rÄ«vmaiņas ā€” lietotāja ceļŔ uz paÅ”reizējo lapu ar iespēju atgriezties jebkurā lÄ«menÄ«. Vecajā ISP sistēmas dokumentācijā jums bija jāiziet no raksta, lai piekļūtu saturam. Tas bija neērti, tāpēc mēs to salabojām jaunajā.

Ievietojiet saites izstrādājumā. Ja cilvēki atkal un atkal vērÅ”as pie atbalsta ar vienu un to paÅ”u jautājumu, ir lietderÄ«gi saskarnei pievienot mājienu ar tā risinājumu. Ja jums ir dati vai ieskats par to, kad lietotājam ir radusies problēma, varat arÄ« informēt viņu, izmantojot adresātu sarakstu. Parādiet viņiem rÅ«pes un noņemiet slogu no atbalsta.

Lietotāja dokumentācija: kas padara to par sliktu un kā to labot
UznirstoŔā loga labajā pusē ir saite uz rakstu par DNSSEC iestatÄ«Å”anu ISPmanager domēna pārvaldÄ«bas sadaļā

Iestatiet savstarpējas atsauces dokumentācijā. Rakstiem, kas ir saistÄ«ti viens ar otru, jābÅ«t ā€œsaistÄ«tiemā€. Ja raksti ir secÄ«gi, katra teksta beigās noteikti pievienojiet uz priekÅ”u un atpakaļ vērstas bultiņas.

Visticamāk, cilvēks vispirms dosies meklēt atbildi uz savu jautājumu nevis jums, bet meklētājprogrammā. Žēl, ja tehnisku iemeslu dēļ nav saiÅ”u uz dokumentāciju. Tāpēc rÅ«pējieties par meklētājprogrammu optimizāciju.

4. problēma. Novecojis izkārtojums traucē uztveri

Papildus sliktiem tekstiem dokumentāciju var sabojāt dizains. Cilvēki ir pieraduÅ”i lasÄ«t labi uzrakstÄ«tus materiālus. Blogi, sociālie tÄ«kli, mediji ā€“ viss saturs tiek pasniegts ne tikai skaisti, bet arÄ« viegli lasāms un acij tÄ«kams. Tāpēc jÅ«s varat viegli saprast sāpes, ko rada persona, kura redz tekstu, kā parādÄ«ts zemāk esoÅ”ajā ekrānuzņēmumā.

Lietotāja dokumentācija: kas padara to par sliktu un kā to labot
Å ajā rakstā ir tik daudz ekrānuzņēmumu un izcēlumu, ka tie nepalÄ«dz, bet tikai traucē uztveri (attēlā var noklikŔķināt)

No dokumentācijas nevajadzētu lasīt ar daudzām sekām, taču ir jāņem vērā pamatnoteikumi.

Izkārtojums. Nosakiet pamatteksta platumu, fontu, izmēru, virsrakstus un polsterējumu. Noalgojiet dizaineru un, lai pieņemtu darbu vai izdarÄ«tu to pats, izlasiet Artjoma Gorbunova grāmatu ā€œTipogrāfija un izkārtojumsā€. Tas parāda tikai vienu izkārtojuma skatu, taču tas ir pilnÄ«gi pietiekami.

PieŔķīrumi. Nosakiet, kas tekstā ir jāuzsver. Parasti tas ir ceļŔ saskarnē, pogās, koda ievietojumos, konfigurācijas failos, ā€œLÅ«dzu, ņemiet vērāā€ blokos. Noteikt, kādi bÅ«s Å”o elementu pieŔķīrumi, un ierakstÄ«t tos nolikumā. Paturiet prātā, ka jo mazāk izdalÄ«jumu, jo labāk. Ja to ir daudz, teksts ir trokŔņains. Pat pēdiņas rada troksni, ja tās tiek lietotas pārāk bieži.

EkrānŔāviņi. Vienojieties ar komandu, kādos gadÄ«jumos ir nepiecieÅ”ami ekrānuzņēmumi. Noteikti nevajag ilustrēt katru soli. Liels skaits ekrānuzņēmumu, t.sk. atseviŔķas pogas, traucē uztveri, sabojā izkārtojumu. Nosakiet ekrānuzņēmumu izcēlumu un parakstu izmēru, kā arÄ« formātu un ierakstiet tos nolikumā. Atcerieties, ka ilustrācijām vienmēr jāatbilst rakstÄ«tajam un jābÅ«t atbilstoŔām. Atkal, ja produkts tiek regulāri atjaunināts, bÅ«s grÅ«ti izsekot visiem.

Teksta garums. Izvairieties no pārāk gariem rakstiem. Sadaliet tos daļās un, ja tas nav iespējams, pievienojiet saturu ar enkura saitēm raksta sākumā. VienkārÅ”s veids, kā padarÄ«t rakstu vizuāli Ä«sāku, ir paslēpt zem spoilera tehniskās detaļas, kas nepiecieÅ”amas Å”auram lasÄ«tāju lokam.

Formāti. Apvienojiet savos rakstos vairākus formātus: tekstu, video un attēlus. Tas uzlabos uztveri.

Nemēģiniet slēpt problēmas ar skaistu izkārtojumu. GodÄ«gi sakot, mēs paÅ”i cerējām, ka ā€œiesaiņojumsā€ izglābs novecojuÅ”o dokumentāciju - tas neizdevās. Tekstos bija tik daudz vizuāla trokŔņa un nevajadzÄ«gu detaļu, ka noteikumi un jaunais dizains bija bezspēcÄ«gi.

Lielu daļu no iepriekÅ” minētā noteiks platforma, kuru izmantojat dokumentācijai. Piemēram, mums ir Confluence. Man arÄ« nācās ar viņu Ä·erties. Ja interesē, izlasiet mÅ«su tÄ«mekļa izstrādātāja stāstu: SabiedrÄ«bas zināŔanu bāzes saplÅ«Å”ana: dizaina maiņa un atdalÄ«Å”anas pa valodām iestatÄ«Å”ana.

Kur sākt pilnveidoties un kā izdzīvot

Ja jÅ«su dokumentācija ir tikpat plaÅ”a kā ISPsystem un jÅ«s nezināt, ar ko sākt, sāciet ar lielākajām problēmām. Klienti nesaprot dokumentu - pilnveido tekstus, veido noteikumus, apmāca rakstÄ«tājus. Dokumentācija ir novecojusi ā€“ rÅ«pējieties par iekŔējiem procesiem. Sāciet ar populārākajiem rakstiem par populārākajiem produktiem: jautājiet atbalstam, skatiet vietņu analÄ«zi un vaicājumus meklētājprogrammās.

Teiksim uzreiz ā€“ viegli nebÅ«s. Un maz ticams, ka tas arÄ« ātri darbosies. Ja vien jÅ«s tikai sākat darbu un nekavējoties nerÄ«kojaties pareizi. Viena lieta, ko mēs noteikti zinām, ir tā, ka laika gaitā tas uzlabosies. Bet process nekad nebeigsies :-).

Avots: www.habr.com

Pievieno komentāru