Dokumentacija softvera samo je skup članaka. No, čak i oni mogu biti frustrirajući. Prvo, dugo tražite potrebne upute. Zatim se borite s nerazumljivim tekstom. Radite kako je napisano, a problem se ne rješava. Tražite drugi članak, nervirate se... Nakon sat vremena odustajete. Tako funkcionira loša dokumentacija. Što je čini takvom i kako to popraviti — pročitajte u nastavku.
Našoj staroj dokumentaciji nedostajalo je mnogo stvari. Već skoro godinu dana je preradimo kako navedeni scenarij ne bi zahvatio naše klijente. Pogledajte, i .
Problem 1. Nerazumljivi, loše napisani članci
Ako se u dokumentaciji ne možeš snaći, kakva je njena svrha? No nitko ne piše nerazumljive članke namjerno. Oni nastaju kada autor ne razmišlja o publici i cilju, piše općenito i ne provjerava tekst na greške.
- Publika. Prije pisanja članka treba razmisliti o razini pripremljenosti čitatelja. Logično je da u članku za početnike ne bi trebali izostavljati osnovne korake i ostavljati tehničke termine bez objašnjenja, dok bi u članku o rijetkoj funkciji koja je potrebna samo profesionalcima trebalo razjasniti značenje riječi PHP.
- Cilj. Još jedna stvar o kojoj je bolje razmisliti unaprijed. Autor mora postaviti jasnu svrhu, definirati korisnu radnju članka, odlučiti što će čitatelj napraviti nakon što ga pročita. Ako se to ne uradi, dobit će se opis radi opisa.
- Suvišne informacije i greške. Puno nepotrebnih informacija i birokratskog jezika, greške i tipfelovi otežavaju razumijevanje. Čak i ako čitatelj nije gramatički pedantan, neurednost u tekstu može ga odbiti.
Uzmite u obzir savjete iznad, i članci će postati razumljiviji — zagarantirano. Da biste još bolje, iskoristite naša .
Problem 2. Članci ne odgovaraju na sva pitanja
Loše je kada dokumentacija ne prati razvoj, ne odgovara na stvarna pitanja, a greške u njoj se ne ispravljaju godinama. To su problemi ne samo autora, nego i organizacije procesa unutar kompanije.
Dokumentacija ne prati razvoj
Značajka je već u objavi, marketing planira njezino predstavljanje, a onda se ispostavi da u dokumentaciji još uvijek nema novog članka ili prevoda. Zbog toga smo čak morali odgoditi objavu. Možemo koliko god željeti tražiti od svih da pravovremeno proslijede zadatak tehničkim piscima, ali to neće uspjeti. Ako proces ne automatiziramo, situacija će se ponavljati.
Unijeli smo promjene u YouTrack. Zadatak za pisanje članka o novoj značajki odmah pada tehničkom piscu kad počnu ispitivati mogućnost. U to vrijeme marketing također saznaje za to kako bi se pripremio za promociju. Obavijesti također dolaze u korporativni messenger Mattermost, pa je jednostavno nemoguće propustiti novosti od programera.
Dokumentacija ne odražava zahtjeve korisnika
Navikli smo raditi ovako: značajka je objavljena, mi o njoj govorimo. Opisujemo kako uključiti, isključiti, izvršiti fine postavke. Ali što ako klijent koristi naš softver na način koji nismo očekivali? Ili ima pogreške o kojima nismo razmišljali?
Kako bi dokumentacija bila što potpunija, preporučujemo analizu poziva u podršku, pitanja na tematskim forumima, pretraživanja na internetu. Najpopularnije teme treba prenijeti tehničkim piscima kako bi dopunili postojeće članke ili napisali nove.
Dokumentacija se ne usavršava
Teško je odmah postići savršenstvo, pogreške će se ionako pojaviti. Možemo se osloniti na povratne informacije od korisnika, ali malo je vjerojatno da će prijavljivati svaku tipfeler, netočnost, nejasan ili nenapisan članak. Osim korisnika, dokumentaciju čitaju i zaposlenici, što znači da vide iste greške. To se može iskoristiti! Treba samo stvoriti uvjete u kojima će biti lako prijaviti problem.
Imamo grupu na unutarnjem portalu gdje zaposlenici ostavljaju primjedbe, prijedloge i ideje za dokumentaciju. Treba članka podršci, a njega nema? Testirač je primijetio netočnost? Partner se žalio menadžerima za razvoj zbog grešaka? Sve ide u ovu grupu! Tehnički pisci neki odmah ispravljaju, neki prenose u YouTrack, a neki uzimaju da razmisle. Kako tema ne bi utihnula, s vremena na vrijeme podsjećamo na postojanje grupe i važnost povratne informacije.
Problema 3. Potreban članak teško je dugo tražiti
Članak koji se ne može pronaći nije bolji od članka koji ne postoji. Motto dobre dokumentacije trebao bi biti rečenica "Lako pretražiti, lako pronaći". Kako to postići?
Urediti strukturu i odrediti princip odabira tema. Struktura treba biti što je moguće transparentnija, kako čitatelj ne bi razmišljao "Gdje mogu pronaći ovaj članak?". Učvrstimo, postoje dva pristupa: od sučelja i od zadataka.
- Od sučelja. Sadržaj duplicira odjeljke u ploči. Tako je bilo u staroj dokumentaciji ISPsystem.
- Od zadataka. Naslovi članaka i odjeljaka odražavaju zadatke korisnika; u naslovima gotovo uvijek postoje glagoli i odgovori na pitanje "kako napraviti". Sada prelazimo na takav format.
Bilo koji pristup da odaberete, osigurajte da tema odgovara zahtjevima korisnika i da je obrađena tako da korisnik sigurno riješi svoje pitanje.
Uspostaviti centralizirano pretraživanje. U idealnom svijetu pretraživanje bi trebala raditi, čak i kada napravite tipkarsku grešku ili pogriješite s jezikom. Naše pretraživanje u Confluenceu još ne može to pružiti. Ako imate mnogo proizvoda, a dokumentacija je zajednička, prilagodite pretraživanje prema stranici na kojoj se korisnik nalazi. U našem slučaju pretraživanje na glavnoj stranici radi za sve proizvode, a ako ste već u određenom odjeljku, onda samo za članke u njemu.
Dodati sadržaj i "krušne mrvice". Dobro je kada na svakoj stranici postoji meni i krušne mrvice - put korisnika do trenutne stranice s mogućnošću povratka na biloću razinu. U staroj dokumentaciji ISPsystem trebalo je napustiti članak kako bi se došlo do sadržaja. Bilo je neugodno, zato smo to u novoj dokumentaciji popravili.
Postaviti linkove u proizvodu. Ako se korisnici iznova obraćaju podršci s istim pitanjem, razumno je dodati napomenu s rješenjem u sučelje. Ako imate podatke ili shvaćate u kojem trenutku korisnik nailazi na problem, također možete obavijestiti putem maila. Na taj način ćete se brinuti i smanjiti opterećenje podrške.
S desne strane u iskušavajućem prozoru poveznica na članak o postavljanju DNSSEC-a u odjeljku upravljanja domenama ISPmanager
Postaviti međusobne poveznice unutar dokumentacije. Članci koji su međusobno povezani trebaju biti „linkovani“. Ako su članci deo niza, obavezno dodajte strelice napred i nazad na kraju svakog teksta.
Verovatno će osoba prvo tražiti odgovor na svoje pitanje ne kod vas, već u pretraživaču. Bilo bi žalosno ako ne bude linkova na dokumentaciju iz tehničkih razloga. Zato se postarajte o SEO optimizaciji.
Problem 4. Zastarela struktura ometa percepciju
Osim loših tekstova, dokumentaciju može pokvariti i dizajn. Ljudi su navikli da čitaju dobro strukturirane materijale. Blogovi, društvene mreže, mediji — sav sadržaj se predstavlja ne samo lepo, već i udobno za čitanje i prijatno za oko. Zbog toga je lako razumeti bol osobe koja vidi tekst poput onog na donjoj slici.
U ovom članku ima toliko mnogo snimaka i obeležavanja da oni ne pomažu, već samo ometaju percepciju (slika je klikabilna)
Ne treba praviti od dokumentacije longread sa gomilom efekata, ali osnovna pravila treba poštovati.
Struktura. Odredite širinu glavnog teksta, font, veličinu, naslove i razmake. Uključite dizajnera, a da biste prihvatili rad ili se snašli sami, pročitajte knjigu Artema Gorbunova „Tipografija i struktura“. Oni predstavljaju samo jedan od pogleda na strukturu, ali je sasvim dovoljan.
Obeležavanja. Definišite šta zahteva akcentovanje u tekstu. Obično je to putanja u interfejsu, dugmad, unosi koda, konfiguracione datoteke, blokovi „Obratite pažnju“. Odredite kakva će biti obeležavanja tih elemenata i zabeležite u pravilniku. Imajte na umu da je manje obeležavanja bolje. Kada ih je mnogo, tekst „šumi“. Šum takođe mogu praviti i navodnici kada se previše koriste.
Snimci ekrana. Dogovorite se s timom u kojim slučajevima su potrebni snimci ekrana. Nije neophodno ilustrirati svaki korak. Velika količina snimaka ekrana, uključujući pojedinačne dugmiće, ometa percepciju i kvare strukturu. Odredite veličinu, kao i format obeležavanja i natpisa na snimcima ekrana, i zabeležite u pravilniku. Zapamtite, ilustracije uvek moraju odgovarati napisanom i biti ažurirane. Ponovo, ako se proizvod redovno ažurira, teško će se pratiti svaka promena.
Dužina teksta. Izbjegavajte preduge članke. Razdvojite ih na dijelove, a ako to nije moguće, dodajte sadržaj s sidrenim linkovima na početak članka. Jednostavan način da članak vizualno izgleda kraće je da skrivene tehničke detalje koji su potrebni uskom krugu čitatelja stavite pod spoiler.
Formati. Kombinirajte više formata u člancima: tekst, video i slike. To će poboljšati doživljaj.
Ne pokušavajte sakriti probleme lijepom izradom. Iskreno, i sami smo se nadali da će 'umotavanje' spasiti zastarjelu dokumentaciju — nije ispalo. U tekstovima je bilo toliko vizualnog šuma i nepotrebnih pojedinosti da su pravila i novi dizajn bili nemoćni.
Mnogo od gore navedenog ovisit će o platformi koju koristite za dokumentaciju. Nama je, na primjer, to Confluence. S njom je također bilo potrebno malo se potruditi. Ako vas zanima, pročitajte priču našeg web-developera: .
Kako započeti poboljšanja i kako preživjeti
Ako je vaša dokumentacija jednako obimna kao kod ISPsystema i ne znate odakle krenuti, počnite s najznačajnijim problemima. Klijenti ne razumiju dokumentaciju — posvetite se poboljšanju tekstova, izradite pravila, obučite pisce. Dokumentacija nije ažurna — pozabavite se unutarnjim procesima. Počnite s najpopularnijim člancima o najtraženijim proizvodima: pitajte podršku, pogledajte analitiku stranice i upite u pretraživačima.
Recimo odmah — neće biti lako. A vjerojatno ni brzo. Osim ako tek počinjete i odmah radite ispravno. Jedno znamo sigurno — s vremenom će biti bolje. No, proces nikada neće završiti :-).
Izvor: habr.com
