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, и .
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 .
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.
- No saskarnes. Saturs dublē paneļa sadaļas. Tā tas bija vecajā ISP sistēmas dokumentācijā.
- 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.
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ā.
Š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: .
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
