Documentația software este pur și simplu un set de articole. Dar chiar și acestea pot deveni frustrante. Mai întâi cauți mult timp instrucțiunile necesare. Apoi te descurci cu un text greu de înțeles. Faci așa cum este scris, dar problema nu se rezolvă. Ai nevoie de un alt articol, te enervezi… După o oră renunți la tot și pleci. Așa funcționează o documentație slabă. Ce o face astfel și cum o putem îmbunătăți — citiți mai departe.
În documentația noastră veche existau multe deficiențe. Deja aproape un an o revizuim pentru ca scenariul menționat mai sus să nu afecteze clienții noștri. Uitați-vă la și .
Problema 1. Articole neclare și prost scrise
Dacă nu poți înțelege documentația, care este sensul ei? Dar nimeni nu scrie articole neclare intenționat. Acestea apar atunci când autorul nu se gândește la public și la scop, se pierde în detalii și nu verifică textul pentru erori.
- Publicul. Înainte de a scrie un articol, trebuie să te gândești la nivelul de pregătire al cititorului. Este logic că, în articolele pentru începători, nu ar trebui să omitem pașii de bază și să lăsăm termenii tehnici neexplicați, iar în articolele despre caracteristici rare, necesare doar profesioniștilor, să explicăm semnificația cuvântului PHP.
- Scop. Un alt aspect de care ar trebui să te gândești din timp. Autorul trebuie să stabilească un obiectiv clar, să definească acțiunea utilă a articolului, să decidă ce va face cititorul după ce l-a citit. Dacă nu se face acest lucru, va rezulta o descriere doar de dragul descrierii.
- Informații inutile și erori. Multe informații excesive și jargon, greșeli și typografii îngreunează percepția. Chiar și dacă cititorul nu este foarte exigent, neglijența în text poate să-l alunge.
Țineți cont de sfaturile de mai sus și articolele vor deveni mai clare — garantat. Pentru a face și mai bine, folosiți .
Problema 2. Articolele nu răspund la toate întrebările
Este rău când documentația nu ține pasul cu dezvoltarea, nu răspunde la întrebările reale, erorile din ea nu sunt corectate de ani de zile. Acestea sunt probleme nu atât ale autorului, cât ale organizării proceselor din cadrul companiei.
Documentația nu ține pasul cu dezvoltarea
Funcția este deja lansată, marketingul plănuiește să o promoveze, iar aici se dovedește că nu există încă un articol sau o traducere în documentație. Din această cauză, a trebuit chiar să amânăm lansarea. Putem să cerem tuturor să transmită sarcina scriitorilor tehnici la timp, dar asta nu va funcționa. Dacă procesul nu este automatizat, situația se va repeta.
Am adus modificări în YouTrack. Sarcina de a scrie un articol despre noua funcție cade asupra scriitorului tehnic în momentul în care posibilitatea începe să fie testată. Atunci marketingul află despre ea pentru a se pregăti pentru promovare. Notificările ajung de asemenea în messengerul corporativ Mattermost, așa că este imposibil să ratezi noutățile de la dezvoltatori.
Documentația nu reflectă nevoile utilizatorilor.
Ne-am obișnuit să lucrăm astfel: funcția a fost lansată, am vorbit despre ea. Am descris cum să o activăm, să o dezactivăm, să facem ajustări fine. Dar ce se întâmplă dacă clientul folosește software-ul nostru în moduri pe care nu le-am anticipat? Sau întâlnește erori pe care nu le-am gândit?
Pentru ca documentația să fie cât mai completă, recomandăm să analizăm solicitările în suport, întrebările de pe forumuri tematice și căutările pe motoarele de căutare. Cele mai populare subiecte trebuie transmise scriitorilor tehnici, astfel încât aceștia să completeze articolele existente sau să scrie altele noi.
Documentația nu se îmbunătățește.
Este greu să realizăm un document perfect din prima, vor exista oricum erori. Putem să ne bazăm pe feedback-ul clienților, dar puțini dintre ei vor raporta fiecare greșeală tipografică, inexactitate, articol neclar sau neidentificat. Pe lângă clienți, documentația este citită și de angajați, așa că și ei observă aceleași erori. Acest lucru poate fi folosit! Trebuie doar să creăm condiții în care să fie ușor să raportăm o problemă.
Avem un grup pe portalul intern, unde angajații lasă observații, sugestii și idei privind documentația. Suportul are nevoie de un articol, dar nu există? Testabilul a observat o inexactitate? Un partener s-a plâns managerilor de dezvoltare despre greșeli? Totul ajunge în acest grup! Scriitorii tehnici corectează imediat unele lucruri, altele le mută în YouTrack, iar unele le iau în considerare. Ca să nu uităm subiectul, răspundem din când în când despre existența grupului și despre importanța feedback-ului.
Problema 3. Articolul necesar trebuie căutat mult timp.
Un articol care nu poate fi găsit nu este mai bun decât un articol care nu există. Deviza unei bune documentații ar trebui să fie fraza „Ușor de căutat, ușor de găsit”. Cum putem realiza acest lucru?
Structura trebuie să fie ordonată și să stabilească principiul de alegere a temelor. Structura ar trebui să fie cât mai transparentă, astfel încât cititorul să nu se întrebe „Unde pot găsi acest articol?”. În general, există două abordări: de la interfață și de la sarcini.
- De la interfață. Conținutul duplică sectoarele din panou. Așa a fost în vechea documentație ISPsystem.
- De la sarcini. Titlurile articolelor și secțiunilor reflectă sarcinile utilizatorilor; în titluri există aproape întotdeauna verbe și răspunsuri la întrebarea „cum să fac”. Acum trecem la un astfel de format.
Indiferent de abordarea pe care o alegeți, asigurați-vă că tema corespunde cerințelor utilizatorilor și este acoperită astfel încât utilizatorul să își rezolve cu certitudine problema.
Organizați o căutare centralizată. Într-o lume ideală, căutarea ar trebui să funcționeze, chiar și atunci când greșești sau faci o eroare de limbaj. Căutarea noastră în Confluence nu poate oferi acest lucru în prezent. Dacă aveți multe produse, iar documentația este generală, adaptați căutarea în funcție de pagina pe care se află utilizatorul. În cazul nostru, căutarea de pe pagina principală funcționează pentru toate produsele, iar dacă sunteți deja într-o secțiune specifică, atunci doar pentru articolele din aceasta.
Adăugați un cuprins și „firimituri”. Este bine când fiecare pagină are un meniu și firimituri — calea utilizatorului până la pagina curentă cu posibilitatea de a se întoarce la orice nivel. În vechea documentație ISPsystem trebuia să ieși din articol pentru a accesa cuprinsul. Era incomod, așa că în noul format am corectat asta.
Plasați linkuri în produs. Dacă oamenii vin din nou și din nou la suport cu aceeași întrebare, este înțelept să adăugați un indiciu cu soluția în interfață. Dacă aveți date sau înțelegere cu privire la momentul în care utilizatorul se confruntă cu o problemă, îl puteți, de asemenea, notifica printr-un newsletter. Și astfel veți arăta grijă, și veți reduce povara de pe suport.
În dreapta, în fereastra pop-up se află un link la articolul despre configurarea DNSSEC în secțiunea de gestionare a domeniilor ISPmanager
Configurați linkuri între documentații. Articolele care sunt legate între ele trebuie să fie „linkuite”. Dacă articolele reprezintă o secvență, asigurați-vă că la sfârșitul fiecărui text se adaugă săgeți înainte și înapoi.
Cel mai probabil, o persoană va căuta răspunsul la întrebarea sa nu la voi, ci în motorul de căutare. Este frustrant dacă nu există linkuri către documentație din motive tehnice. Așadar, aveți grijă de optimizarea pentru motoarele de căutare.
Problema 4. Designul învechit interferează cu percepția.
Pe lângă textele slabe, designul poate strica documentația. Oamenii sunt obișnuiți să citească materiale bine realizate. Blogurile, rețelele sociale, mass-media — tot conținutul este prezentat nu doar frumos, ci și ușor de citit, plăcut ochiului. De aceea, este ușor de înțeles durerea unei persoane care vede textul ca în captura de ecran de mai jos.
În acest articol, numărul de capturi de ecran și sublinieri este atât de mare încât nu ajută, ci doar interferează cu percepția (imaginea este clicabilă).
Nu ar trebui să transformați documentația într-un longread cu o mulțime de efecte, dar trebuie să luați în considerare regulile de bază.
Design. Determinați lățimea textului principal, fontul, dimensiunea, titlurile și marginile. Implicați un designer și, pentru a accepta munca sau a face față singuri, citiți cartea lui Artem Gorbunov „Tipografie și design”. Aceasta oferă doar una dintre perspectivele asupra designului, dar este mai mult decât suficientă.
Subliniere. Stabiliți ce necesită accentuare în text. De obicei, acestea sunt calea în interfață, butoane, inserții de cod, fișiere de configurație, blocuri „Acordați atenție”. Stabiliți cum vor arăta aceste sublinieri și documentați în reglementare. Amintiți-vă că cu cât sunt mai puține sublinieri, cu atât mai bine. Când sunt multe, textul devine „zgomotos”. Zgomotul este creat chiar și de ghilimele, dacă sunt folosite prea frecvent.
Capturi de ecran. Negociați cu echipa în ce situații sunt necesare capturi de ecran. Nu este nevoie să ilustrați fiecare pas. Un număr mare de capturi de ecran, inclusiv de butoane individuale, interferează cu percepția și strică designul. Stabiliți dimensiunea, precum și formatul sublinierilor și descrierilor pe capturile de ecran, și documentați în reglementare. Amintiți-vă că ilustrațiile trebuie întotdeauna să corespundă ceea ce este scris și să fie actuale. Din nou, dacă produsul se actualizează frecvent, va fi greu să țineți pasul cu fiecare.
Lungimea textului. Evitați articolele excesiv de lungi. Împărțiți-le în părți, iar dacă nu este posibil, adăugați la începutul articolului un cuprins cu linkuri ancorate. O modalitate simplă de a face articolul să pară vizual mai scurt este să ascundeți detaliile tehnice, necesare unui cerc restrâns de cititori, sub un spoiler.
Formate. Combinați mai multe formate în articole: text, video și imagini. Acest lucru va îmbunătăți percepția.
Nu încercați să acoperiți problemele cu un design frumos. Sincer, ne-am sperat că «ambalajul» va salva documentația învechită — dar nu a funcționat. În texte era atât de mult zgomot vizual și detalii inutile, încât reglementările și noul design au fost fără putere.
Multe din cele menționate mai sus vor fi determinante de platforma pe care o folosiți pentru documentare. De exemplu, pentru noi, aceasta este Confluence. A trebuit să ne ocupăm și de el. Dacă sunteți interesați, citiți povestea dezvoltatorului nostru web: .
De unde să începeți îmbunătățirile și cum să supraviețuiți
Dacă documentația dvs. este la fel de vastă ca cea a ISPsystem și nu știți de unde să începeți, începeți cu cele mai serioase probleme. Clienții nu înțeleg documentația — ocupați-vă de îmbunătățirea textelor, elaborați reglementări, instruiți scriitorii. Documentația nu este actuală — ocupați-vă de procesele interne. Începeți cu cele mai populare articole despre produsele cele mai căutate: întrebați suportul, analizați analitica site-ului și căutările în motoarele de căutare.
Să spunem clar — nu va fi ușor. Și rapid, de asemenea, nu va fi probabil. Cu excepția cazului în care abia începeți și faceți totul corect de la bun început. Un lucru știm cu siguranță — cu timpul va fi mai bine. Dar procesul nu se va încheia niciodată :-).
Sursa: habr.com
