Softverska dokumentacija samo je skup članaka. Ali čak te i oni mogu izluditi. Prvo, dugo ćete tražiti potrebne upute. Tada razumijete opskurni tekst. Radite kako je napisano, ali problem nije riješen. Tražiš drugi članak, postaješ nervozan... Sat vremena kasnije odustaješ od svega i odlaziš. Ovako funkcionira loša dokumentacija. Zbog čega je ovakva i kako to popraviti - pročitajte pod rezom.
U našoj staroj dokumentaciji bilo je mnogo nedostataka. Već gotovo godinu dana ga prerađujemo kako gore opisani scenarij ne bi utjecao na naše klijente. Izgled, и .
Problem 1: Nejasni, loše napisani članci
Ako je dokumentaciju nemoguće razumjeti, koja je svrha toga? Ali nitko ne piše nerazumljive članke namjerno. Događaju se kada autor ne razmišlja o publici i svrsi, nalijeva vodu i ne provjerava tekst za pogreške.
- Publika. Prije nego što napišete članak, morate razmisliti o razini pripremljenosti čitatelja. Logično je da u članku za početnika ne biste trebali preskočiti osnovne korake i ostaviti tehničke pojmove bez objašnjenja, ali u članku o rijetkoj značajci koja je potrebna samo profesionalcima, trebali biste objasniti značenje riječi PHP.
- Cilj. Još jedna stvar o kojoj treba unaprijed razmisliti. Autor mora postaviti jasan cilj, odrediti koristan učinak članka i odlučiti što će čitatelj učiniti nakon što ga pročita. Ako se to ne učini, završit ćete s opisom radi opisa.
- Voda i bube. Puno je nepotrebnih informacija i birokracije, pogreške i pravopisne pogreške ometaju percepciju. Čak i ako čitatelj nije gramatički nacist, nepažnja u tekstu može ga odbiti.
Uzmite u obzir gornje savjete i članci će postati jasniji - zajamčeno. Da biste ga učinili još boljim, koristite naš .
Problem 2. Članci ne odgovaraju na sva pitanja
Loše je kada dokumentacija ne prati razvoj, ne odgovara na stvarna pitanja, a pogreške u njoj se godinama ne ispravljaju. To su problemi ne toliko autora, koliko organizacije procesa unutar tvrtke.
Dokumentacija ne prati razvoj
Značajka je već u izdanju, marketing planira to pokriti, a onda se ispostavi da novi članak ili prijevod još uvijek nisu u dokumentaciji. Zbog toga smo čak morali odgoditi izlazak. Možete tražiti od svih da predaju zadatke tehničkim piscima na vrijeme koliko god želite, ali to neće ići. Ako proces nije automatiziran, situacija će se ponoviti.
Napravili smo izmjene na YouTracku. Zadatak pisanja članka o novoj značajki pada na tehničkog pisca u istom trenutku kada se značajka počne testirati. Tada marketing uči o tome kako bi se pripremio za promociju. Obavijesti također dolaze u korporativni glasnik Mattermost, tako da je jednostavno nemoguće propustiti novosti od programera.
Dokumentacija ne odražava zahtjeve korisnika
Navikli smo tako raditi: pojavi se prilog, razgovaramo o tome. Opisali smo kako ga uključiti, isključiti i napraviti fina podešavanja. Ali što ako klijent koristi naš softver na način na koji nismo očekivali? Ili ima grešaka o kojima nismo razmišljali?
Kako bismo bili sigurni da je dokumentacija što potpunija, preporučujemo analizu zahtjeva za podršku, pitanja na tematskim forumima i upita u tražilicama. Najpopularnije teme bit će prebačene tehničkim piscima kako bi mogli nadopuniti postojeće članke ili napisati nove.
Dokumentacija se ne poboljšava
Teško je to učiniti savršeno odmah; i dalje će biti grešaka. Možete se nadati povratnim informacijama od kupaca, ali malo je vjerojatno da će oni prijaviti svaku tipfelersku pogrešku, netočnost, nerazumljiv ili nepronađen članak. Osim klijenata, dokumentaciju čitaju i zaposlenici, što znači da vide iste greške. Ovo se može koristiti! Samo trebate stvoriti uvjete u kojima će biti lako prijaviti problem.
Na internom portalu imamo grupu u kojoj zaposlenici ostavljaju komentare, prijedloge i ideje na dokumentaciju. Treba li podrška članku, ali on ne postoji? Je li tester primijetio netočnost? Je li se partner žalio voditeljima razvoja na pogreške? Svi u ovu grupu! Tehnički pisci neke stvari popravljaju odmah, neke prenose na YouTrack, a drugima daju malo vremena za razmišljanje. Kako tema ne bi zamrla, s vremena na vrijeme podsjećamo na postojanje grupe i važnost povratne informacije.
Problem 3. Potrebno je puno 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 za pretraživanje, lako za pronaći." Kako to postići?
Organizirati strukturu i odrediti princip odabira tema. Struktura bi trebala biti što transparentnija kako čitatelj ne bi pomislio: "Gdje mogu pronaći ovaj članak?" Ukratko, postoje dva pristupa: iz sučelja i iz zadataka.
- Iz sučelja. Sadržaj duplicira dijelove ploče. To je bio slučaj u staroj dokumentaciji ISPsystema.
- Od zadataka. Naslovi članaka i odjeljaka 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 konkretno bavi pitanjem korisnika.
Postavite centralizirano pretraživanje. U idealnom svijetu, pretraživanje bi trebalo funkcionirati čak i kada pogrešno napišete ili pogriješite u jeziku. Naša dosadašnja potraga u Confluenceu ne može nas zadovoljiti ovime. Ako imate mnogo proizvoda, a dokumentacija je općenita, prilagodite pretraživanje 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đenoj rubrici, onda samo za artikle u njoj.
Dodajte sadržaj i prezle. Dobro je kada svaka stranica ima izbornik i puteve - put korisnika do trenutne stranice s mogućnošću povratka na bilo koju razinu. U staroj dokumentaciji ISPsystema morali ste izaći iz članka da biste došli do sadržaja. Bilo je nezgodno, pa smo to popravili u novom.
Postavite poveznice u proizvod. Ako ljudi uvijek iznova dolaze na podršku s istim pitanjem, ima smisla dodati savjet s njegovim rješenjem na sučelje. Ako imate podatke ili uvid u to kada korisnik ima problema, možete ga obavijestiti i putem mailing liste. Pokažite im brigu i skinite teret s podrške.
S desne strane u skočnom prozoru nalazi se poveznica na članak o postavljanju DNSSEC-a u odjeljku upravljanja domenom ISPmanagera
Postavite unakrsne reference unutar dokumentacije. Članci koji su međusobno povezani trebaju biti "povezani". Ako su članci jedan za drugim, svakako dodajte strelice naprijed i natrag na kraju svakog teksta.
Najvjerojatnije će osoba prvo potražiti odgovor na svoje pitanje ne vama, već tražilici. Šteta je ako tamo nema poveznica na dokumentaciju iz tehničkih razloga. Stoga vodite računa o optimizaciji za tražilice.
Problem 4. Zastarjeli raspored ometa percepciju
Osim loših tekstova, dokumentaciju zna pokvariti dizajn. Ljudi su navikli čitati dobro napisane materijale. Blogovi, društvene mreže, mediji - svi sadržaji predstavljeni su ne samo lijepim, već i lakim za čitanje i ugodnim za oko. Stoga možete lako razumjeti bol osobe koja vidi tekst kao na slici ispod.
U ovom članku ima toliko screenshotova i highlightsa da ne pomažu, već samo ometaju percepciju (na sliku se može kliknuti)
Od dokumentacije ne treba raditi longread s hrpom efekata, ali morate uzeti u obzir osnovna pravila.
Izgled. Odredite širinu teksta, font, veličinu, naslove i ispunu. Unajmite dizajnera, a ako želite prihvatiti posao ili ga sami obaviti, pročitajte knjigu Artema Gorbunova "Tipografija i izgled". Predstavlja samo jedan pogled na izgled, ali je sasvim dovoljan.
Alokacije. Odredi što u tekstu treba naglasiti. Obično je to put u sučelju, gumbi, umetci koda, konfiguracijske datoteke, blokovi "Napomena". Odredite koliki će biti rasporedi tih elemenata i zabilježite ih u pravilniku. Imajte na umu da što manje iscjetka, to bolje. Kad ih je puno, tekst je bučan. Čak i navodnici stvaraju buku ako se koriste prečesto.
Slike. Dogovorite se s timom u kojim slučajevima su potrebne snimke zaslona. Definitivno nema potrebe ilustrirati svaki korak. Veliki broj snimaka zaslona, uklj. odvojeni gumbi, ometaju percepciju, kvare izgled. Odredite veličinu, kao i format isticanja i potpisa na snimkama zaslona te ih evidentirajte u pravilniku. Ne zaboravite da ilustracije uvijek trebaju odgovarati onome što je napisano i biti relevantne. Opet, ako se proizvod redovito ažurira, bit ć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 sidrenim vezama na početak članka. Jednostavan način vizualnog skraćivanja članka je skrivanje tehničkih detalja potrebnih uskom krugu čitatelja ispod spojlera.
formati. Kombinirajte nekoliko formata u svojim člancima: tekst, video i slike. To će poboljšati percepciju.
Ne pokušavajte prikriti probleme lijepim izgledom. Iskreno, i sami smo se nadali da će "omot" spasiti zastarjelu dokumentaciju - nije uspjelo. Tekstovi su sadržavali toliko vizualne buke i nepotrebnih detalja da su propisi i novi dizajn bili nemoćni.
Velik dio navedenog ovisit će o platformi koju koristite za dokumentaciju. Na primjer, imamo Confluence. Morao sam se i s njim petljati. Ako ste zainteresirani, pročitajte priču našeg web programera: .
Gdje početi s usavršavanjem i kako preživjeti
Ako je vaša dokumentacija opsežna kao ISPsystem i ne znate odakle početi, počnite s najvećim problemima. Naručitelji ne razumiju dokument – poboljšajte tekstove, napravite propise, obučite pisce. Dokumentacija je zastarjela - pobrinite se za interne procese. Započnite s najpopularnijim člancima o najpopularnijim proizvodima: pitajte podršku, pogledajte analitiku stranice i upite u tražilicama.
Recimo odmah – neće biti lako. A malo je vjerojatno da će i brzo djelovati. Osim ako ste tek na početku i odmah učinite pravu stvar. Jedno sigurno znamo je da će s vremenom biti sve bolje. Ali proces nikada neće završiti :-).
Izvor: www.habr.com