Softverska dokumentacija je samo skup članaka. Ali čak i oni mogu da vas izlude. Prvo, dugo ćete tražiti potrebna uputstva. Onda razumete nejasan tekst. Radiš kako je napisano, ali problem nije riješen. Tražiš drugi članak, unervoziš se... Sat vremena kasnije odustaneš od svega i odeš. Ovako funkcionira loša dokumentacija. Šta ga čini ovakvim i kako to popraviti - pročitajte ispod.
U našoj staroj dokumentaciji bilo je mnogo nedostataka. Prerađujemo ga već skoro godinu dana kako gore opisani scenario ne bi uticao na naše klijente. gledaj, и .
Problem 1: Nejasni, loše napisani članci
Ako je dokumentaciju nemoguće razumjeti, koja je svrha toga? Ali niko namerno ne piše nerazumljive članke. Događaju se kada autor ne razmišlja o publici i svrsi, sipa vodu i ne provjerava tekst da li ima grešaka.
- Publika. Prije nego što napišete članak, morate razmisliti o nivou pripreme čitatelja. Logično je da u članku za početnika ne preskačete osnovne korake i ostavljate tehničke termine bez objašnjenja, već u članku o rijetkoj osobini koja je potrebna samo profesionalcima treba objasniti značenje riječi PHP.
- Cilj. Još jedna stvar o kojoj treba razmisliti unaprijed. Autor mora postaviti jasan cilj, odrediti koristan učinak članka i odlučiti šta će čitalac učiniti nakon što ga pročita. Ako to nije učinjeno, na kraju ćete dobiti opis radi opisa.
- Voda i bube. Puno je nepotrebnih informacija i birokratije, greške i tipkarske greške ometaju percepciju. Čak i ako čitalac nije nacista gramatike, nepažnja u tekstu može ga odbiti.
Uzmite u obzir gornje savjete i članci će postati jasniji - garantirano. Da bude još bolje, koristite naše .
Problem 2. Članci ne odgovaraju na sva pitanja
Loše je kada dokumentacija ne ide u korak sa razvojem, ne odgovara na prava pitanja, a greške u njoj se godinama ne ispravljaju. To su problemi ne toliko autora, koliko organizacije procesa unutar kompanije.
Dokumentacija ne ide u korak sa razvojem
Funkcija je već objavljena, marketing planira da je pokrije, a onda se ispostavi da novi članak ili prijevod još uvijek nije u dokumentaciji. Zbog toga smo čak morali i odgoditi izlazak. Možete tražiti od svih da predaju zadatke tehničkim piscima na vrijeme koliko god želite, ali to neće uspjeti. Ako proces nije automatiziran, situacija će se ponoviti.
Napravili smo promjene na YouTrack-u. Zadatak pisanja članka o novoj osobini pada na tehničkog pisca u istom trenutku kada funkcija počinje da se testira. Tada marketing uči o tome kako bi se pripremio za promociju. Obavijesti također stižu u Mattermost korporativni glasnik, tako da je jednostavno nemoguće propustiti vijesti od programera.
Dokumentacija ne odražava zahtjeve korisnika
Navikli smo da radimo ovako: pojavila se funkcija, razgovarali smo o njoj. Opisali smo kako ga uključiti, isključiti i izvršiti fina podešavanja. Ali šta ako klijent koristi naš softver na način na koji nismo očekivali? Ili ima grešaka o kojima nismo razmišljali?
Kako bismo osigurali da je dokumentacija što potpunija, preporučujemo analizu zahtjeva za podršku, pitanja na tematskim forumima i upita u pretraživačima. Najpopularnije teme će biti prebačene tehničkim piscima kako bi mogli dopuniti postojeće članke ili napisati nove.
Dokumentacija se ne poboljšava
Teško je to odmah učiniti savršeno; Možete se nadati povratnim informacijama od kupaca, ali je malo vjerovatno da će prijaviti svaku grešku u kucanju, netačnost, nerazumljiv ili nepronađen članak. Osim klijenata, dokumentaciju čitaju i zaposleni, što znači da vide iste greške. Ovo se može iskoristiti! Potrebno je samo stvoriti uslove u kojima će biti lako prijaviti problem.
Na internom portalu imamo grupu u kojoj zaposleni ostavljaju komentare, sugestije i ideje na dokumentaciju. Da li podršci treba članak, ali ne postoji? Da li je tester primijetio nepreciznost? Da li se partner žalio menadžerima razvoja na greške? Svi u ovoj grupi! Tehnički pisci popravljaju neke stvari odmah, neke stvari prenose na YouTrack, a drugima daju vremena za razmišljanje. Kako tema ne bi zamrla, s vremena na vrijeme vas podsjetimo na postojanje grupe i važnost povratnih informacija.
Problem 3. Potrebno je mnogo vremena da se pronađe pravi članak.
Članak koji se ne može pronaći nije ništa bolji od članka koji se ne može pronaći. Moto dobre dokumentacije trebao bi biti „Lako pretraživati, lako pronaći“. Kako to postići?
Organizujte strukturu i odredite princip izbora tema. Struktura bi trebala biti što transparentnija kako čitatelj ne bi pomislio: „Gdje mogu pronaći ovaj članak?“ Da rezimiramo, postoje dva pristupa: iz interfejsa i iz zadataka.
- Iz interfejsa. Sadržaj duplira sekcije panela. To je bio slučaj u staroj dokumentaciji ISPsystema.
- Od zadataka. Naslovi članaka i sekcija odražavaju zadatke korisnika; Naslovi gotovo uvijek sadrže glagole i odgovore na pitanje “kako”. Sada prelazimo na ovaj format.
Koji god pristup odabrali, pobrinite se da je tema relevantna za ono što korisnici traže i da je pokrivena na način koji se posebno odnosi na pitanje korisnika.
Postavite centraliziranu pretragu. U idealnom svijetu, pretraga bi trebala funkcionirati čak i kada pogrešno napišete ili pogriješite u jeziku. Naša dosadašnja pretraga u Confluenceu ne može nas zadovoljiti ovim. Ako imate mnogo proizvoda i dokumentacija je opća, prilagodite pretragu stranici na kojoj se korisnik nalazi. U našem slučaju, pretraga na glavnoj stranici radi za sve proizvode, a ako ste već u određenom dijelu, onda samo za članke u njemu.
Dodajte sadržaj i prezle. Dobro je kada svaka stranica ima meni i breadcrumbs - put korisnika do trenutne stranice s mogućnošću povratka na bilo koji nivo. U staroj dokumentaciji ISPsystema, morali ste izaći iz članka da biste došli do sadržaja. Bilo je nezgodno, pa smo ga popravili u novom.
Postavite linkove u proizvod. Ako ljudi iznova i iznova dolaze u podršku sa istim pitanjem, ima smisla dodati nagovještaj s njegovim rješenjem u sučelje. Ako imate podatke ili uvid u to kada korisnik ima problem, možete ga obavijestiti i mailing listom. Pokažite im brigu i skinite teret podrške.
Desno u iskačućem prozoru je link na članak o postavljanju DNSSEC-a u odjeljku za upravljanje domenom ISPmanager-a
Postavite unakrsne reference unutar dokumentacije. Članke koji su međusobno povezani treba „povezati“. Ako su članci uzastopni, obavezno dodajte strelice naprijed i nazad na kraj svakog teksta.
Najvjerovatnije će osoba prvo otići tražiti odgovor na svoje pitanje ne vama, već pretraživaču. Šteta ako tamo iz tehničkih razloga nema linkova na dokumentaciju. Zato vodite računa o optimizaciji za pretraživače.
Problem 4. Zastarjeli izgled ometa percepciju
Osim loših tekstova, dokumentaciju može pokvariti i dizajn. Ljudi su navikli čitati dobro napisane materijale. Blogovi, društvene mreže, mediji - sav sadržaj je predstavljen ne samo lijepo, već i lako čitljiv i ugodan oku. Stoga možete lako razumjeti bol osobe koja vidi tekst kao na slici ispod.
U ovom članku ima toliko snimaka ekrana i istaknutih detalja da oni ne pomažu, već samo ometaju percepciju (slika se može kliknuti)
Ne biste trebali praviti longread od dokumentacije sa gomilom efekata, ali morate uzeti u obzir osnovna pravila.
Layout. Odredite širinu teksta, font, veličinu, naslove i padding. Unajmite dizajnera, a da biste prihvatili posao ili ga uradili sami, pročitajte knjigu Artjoma Gorbunova „Tipografija i raspored“. Predstavlja samo jedan pogled na izgled, ali je sasvim dovoljan.
Izdvajanja. Odredite šta je potrebno naglasiti u tekstu. Obično je to putanja u interfejsu, dugmad, umetci koda, konfiguracioni fajlovi, blokovi „Molimo, obratite pažnju“. Odredite koja će biti raspodjela ovih elemenata i zabilježiti ih u pravilniku. Imajte na umu da što manje pražnjenja, to bolje. Kada ih ima puno, tekst je bučan. Čak i navodnici stvaraju buku ako se koriste prečesto.
Snimke ekrana. Dogovorite se sa timom u kojim slučajevima su potrebne snimke ekrana. Definitivno nema potrebe ilustrirati svaki korak. Veliki broj snimaka ekrana, uklj. odvojena dugmad, ometaju percepciju, kvare izgled. Odredite veličinu, kao i format isticanja i potpisa na snimcima ekrana i zapišite ih u pravilnik. Zapamtite da ilustracije uvijek trebaju odgovarati onome što je napisano i biti relevantne. Opet, ako se proizvod redovno ažurira, biće teško pratiti sve.
Dužina teksta. Izbjegavajte preduge članke. Razdvojite ih na dijelove, a ako to nije moguće, dodajte sadržaj sa sidrom na početak članka. Jednostavan način da se članak vizualno skrati je skrivanje tehničkih detalja potrebnih uskom krugu čitatelja ispod spojlera.
Formati. Kombinirajte nekoliko formata u svojim člancima: tekst, video i slike. Ovo će poboljšati percepciju.
Ne pokušavajte prikriti probleme lijepim izgledom. Iskreno, i sami smo se nadali da će "omot" spasiti zastarjelu dokumentaciju - nije išlo. Tekstovi su sadržavali toliko vizualne buke i nepotrebnih detalja da su propisi i novi dizajn bili nemoćni.
Veći dio gore navedenog bit će određen platformom koju koristite za dokumentaciju. Na primjer, imamo Confluence. I ja sam morao da petljam sa njim. Ako ste zainteresirani, pročitajte priču našeg web programera: .
Gdje početi sa usavršavanjem i kako preživjeti
Ako je vaša dokumentacija ogromna kao ISPsystem i ne znate odakle da počnete, počnite s najvećim problemima. Klijenti ne razumiju dokument - poboljšajte tekstove, napravite propise, obučite pisce. Dokumentacija je zastarjela - vodite računa o internim procesima. Počnite s najpopularnijim člancima o najpopularnijim proizvodima: pitajte podršku, pogledajte analitiku stranice i upite u tražilicama.
Recimo odmah – neće biti lako. I malo je vjerovatno da će raditi brzo. Osim ako tek počinjete i odmah ne učinite pravu stvar. Ono što sigurno znamo je da će vremenom biti bolje. Ali proces se nikada neće završiti :-).
izvor: www.habr.com
