Documentația software este doar un set de articole. Dar chiar și ei te pot înnebuni. În primul rând, petreci mult timp căutând instrucțiunile necesare. Atunci înțelegi textul obscur. Faci cum ai scris, dar problema nu este rezolvata. Cauți un alt articol, devii nervos... O oră mai târziu renunți la tot și pleci. Așa funcționează documentația proastă. Ce face ca acesta să fie așa și cum să-l repare - citiți sub tăietură.
Au existat multe neajunsuri în documentația noastră veche. De aproape un an îl reluăm pentru ca scenariul descris mai sus să nu afecteze clienții noștri. Uite, и .
Problema 1: articole neclare, scrise prost
Dacă documentația este imposibil de înțeles, ce rost are ea? Dar nimeni nu scrie intenționat articole de neînțeles. Se întâmplă atunci când autorul nu se gândește la public și la scop, toarnă apă și nu verifică textul pentru erori.
- Publicul. Înainte de a scrie un articol, trebuie să vă gândiți la nivelul de pregătire al cititorului. Este logic ca într-un articol pentru un începător să nu săriți peste pașii de bază și să lăsați termeni tehnici fără explicații, dar într-un articol despre o caracteristică rară de care au nevoie doar profesioniștii, ar trebui să explicați sensul cuvântului PHP.
- Scop. Încă un lucru la care să te gândești în avans. Autorul trebuie să stabilească un obiectiv clar, să determine efectul util al articolului și să decidă ce va face cititorul după ce îl citește. Dacă nu se face acest lucru, veți ajunge cu o descriere de dragul descrierii.
- Apă și insecte. Există o mulțime de informații inutile și birocrație, erorile și greșelile de scriere interferează cu percepția. Chiar dacă cititorul nu este un nazist de gramatică, nepăsarea în text îl poate opri.
Luați în considerare sfaturile de mai sus și articolele vor deveni mai clare - garantate. Pentru a o face și mai bună, folosiți-o .
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ări reale și 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
Caracteristica este deja în lansare, marketingul intenționează să o acopere și apoi se dovedește că noul articol sau traducerea încă nu este în documentație. Chiar și a trebuit să amânăm lansarea din această cauză. Puteți cere tuturor să predea sarcinile scriitorilor tehnici la timp atât cât doriți, dar nu va funcționa. Dacă procesul nu este automatizat, situația se va repeta.
Am făcut modificări la YouTrack. Sarcina de a scrie un articol despre o nouă caracteristică revine scriitorului tehnic în același moment în care caracteristica începe să fie testată. Apoi marketingul învață despre asta pentru a se pregăti pentru promovare. Notificările vin și către messengerul corporativ Mattermost, așa că este pur și simplu imposibil să ratezi știri de la dezvoltatori.
Documentația nu reflectă solicitările utilizatorilor
Suntem obișnuiți să lucrăm așa: a apărut o caracteristică, am vorbit despre asta. Am descris cum să îl porniți, să îl opriți și să faceți ajustări fine. Dar ce se întâmplă dacă un client folosește software-ul nostru într-un mod la care nu ne așteptam? Sau are erori la care nu ne-am gândit?
Pentru a vă asigura că documentația este cât mai completă posibil, vă recomandăm să analizați cererile de asistență, întrebările pe forumuri tematice și interogările din motoarele de căutare. Cele mai populare subiecte vor fi transferate scriitorilor tehnici, astfel încât aceștia să poată completa articolele existente sau să scrie altele noi.
Documentația nu este îmbunătățită
Este dificil să o faci perfect imediat; vor exista încă greșeli. Puteți spera la feedback de la clienți, dar este puțin probabil ca aceștia să raporteze fiecare greșeală de scriere, inexactitate, articol de neînțeles sau negăsit. Pe lângă clienți, angajații citesc documentația, ceea ce înseamnă că văd aceleași erori. Acesta poate fi folosit! Trebuie doar să creați condiții în care va fi ușor să raportați o problemă.
Avem un grup pe portalul intern unde angajații lasă comentarii, sugestii și idei despre documentare. Asistența are nevoie de un articol, dar nu există? Testerul a observat inexactitatea? Partenerul s-a plâns managerilor de dezvoltare despre erori? Toți în acest grup! Scriitorii tehnici remediază unele lucruri imediat, transferă unele lucruri în YouTrack și oferă altora timp să se gândească. Pentru a preveni stingerea subiectului, din când în când vă reamintim de existența grupului și de importanța feedback-ului.
Problema 3. Este nevoie de mult timp pentru a găsi articolul potrivit.
Un articol care nu poate fi găsit nu este mai bun decât un articol care nu poate fi găsit. Motto-ul unei documentări bune ar trebui să fie „Ușor de căutat, ușor de găsit”. Cum să realizezi acest lucru?
Organizați structura și determinați principiul de alegere a subiectelor. Structura ar trebui să fie cât mai transparentă posibil, astfel încât cititorul să nu se gândească „Unde pot găsi acest articol?” Pentru a rezuma, există două abordări: de la interfață și de la sarcini.
- Din interfață. Conținutul dublează secțiunile panoului. Acesta a fost cazul în vechea documentație a sistemului ISP.
- Din sarcini. Titlurile articolelor și secțiunilor reflectă sarcinile utilizatorilor; Titlurile conțin aproape întotdeauna verbe și răspunsuri la întrebarea „cum să”. Acum trecem la acest format.
Indiferent de abordarea pe care o alegeți, asigurați-vă că subiectul este relevant pentru ceea ce caută utilizatorii și este acoperit într-un mod care abordează în mod specific întrebarea utilizatorului.
Configurați o căutare centralizată. Într-o lume ideală, căutarea ar trebui să funcționeze chiar și atunci când scrieți greșit sau faceți o greșeală cu limba. Căutarea noastră în Confluence de până acum nu ne poate mulțumi cu asta. Dacă aveți multe produse și documentația este generală, adaptați căutarea la pagina în care se află utilizatorul. În cazul nostru, căutarea pe pagina principală funcționează pentru toate produsele, iar dacă vă aflați deja într-o anumită secțiune, atunci numai pentru articolele din ea.
Adăugați conținut și pesmet. Este bine când fiecare pagină are un meniu și breadcrumbs - calea utilizatorului către pagina curentă cu posibilitatea de a reveni la orice nivel. În vechea documentație a sistemului ISP, trebuia să părăsiți articolul pentru a ajunge la conținut. A fost incomod, așa că l-am reparat în cel nou.
Plasați linkuri în produs. Dacă oamenii vin să sprijine din nou și din nou cu aceeași întrebare, este logic să adăugați un indiciu cu soluția sa la interfață. Dacă aveți date sau informații despre momentul în care un utilizator se confruntă cu o problemă, îl puteți notifica și printr-o listă de corespondență. Arătați-le îngrijorare și luați povara de pe sprijin.
În partea dreaptă a ferestrei pop-up este un link către un articol despre configurarea DNSSEC în secțiunea de gestionare a domeniilor din ISPmanager
Configurați referințe încrucișate în documentație. Articolele care au legătură între ele ar trebui să fie „legate”. Dacă articolele sunt secvențiale, asigurați-vă că adăugați săgeți înainte și înapoi la sfârșitul fiecărui text.
Cel mai probabil, o persoană va căuta mai întâi un răspuns la întrebarea sa nu pentru tine, ci pentru un motor de căutare. Este păcat dacă nu există link-uri către documentația de acolo din motive tehnice. Așa că aveți grijă de optimizarea motoarelor de căutare.
Problema 4. Aspectul învechit interferează cu percepția
Pe lângă textele proaste, documentația poate fi stricat prin design. Oamenii sunt obișnuiți să citească materiale bine scrise. Bloguri, rețele sociale, media - tot conținutul este prezentat nu numai frumos, ci și ușor de citit și plăcut ochiului. Prin urmare, puteți înțelege cu ușurință durerea unei persoane care vede text ca în captura de ecran de mai jos.
Există atât de multe capturi de ecran și evidențieri în acest articol încât nu ajută, ci doar interferează cu percepția (poza se poate face clic)
Nu ar trebui să citiți îndelung din documentație cu o grămadă de efecte, dar trebuie să țineți cont de regulile de bază.
Aspect. Determinați lățimea textului, fontul, dimensiunea, titlurile și umplutura. Angajați un designer și, pentru a accepta munca sau faceți-o singur, citiți cartea lui Artyom Gorbunov „Tipografie și aspect”. Prezintă o singură vedere a aspectului, dar este destul de suficient.
Alocările. Stabiliți ce necesită accent în text. De obicei, aceasta este o cale în interfață, butoane, inserări de cod, fișiere de configurare, blocuri „Vă rugăm să rețineți”. Stabiliți care vor fi alocările acestor elemente și înscrieți-le în regulament. Rețineți că, cu cât descărcarea este mai mică, cu atât mai bine. Când sunt multe, textul este zgomotos. Chiar și ghilimelele creează zgomot dacă sunt folosite prea des.
Capturi de ecran. De acord cu echipa în ce cazuri sunt necesare capturi de ecran. Cu siguranță nu este nevoie să ilustrăm fiecare pas. Un număr mare de capturi de ecran, inclusiv. butoane separate, interferează cu percepția, strică aspectul. Determinați dimensiunea, precum și formatul evidențierilor și semnăturilor pe capturi de ecran și înregistrați-le în regulamente. Amintiți-vă că ilustrațiile ar trebui să corespundă întotdeauna cu ceea ce este scris și să fie relevante. Din nou, dacă produsul este actualizat în mod regulat, va fi dificil să țineți evidența tuturor.
Lungimea textului. Evitați articolele prea lungi. Împărțiți-le în părți și, dacă acest lucru nu este posibil, adăugați conținut cu link-uri ancora la începutul articolului. O modalitate simplă de a face un articol mai scurt din punct de vedere vizual este să ascundeți sub spoiler detaliile tehnice necesare unui cerc restrâns de cititori.
formate. Combină mai multe formate în articolele tale: text, video și imagini. Acest lucru va îmbunătăți percepția.
Nu încercați să acoperiți problemele cu un aspect frumos. Sincer, noi înșine am sperat că „învelișul” va salva documentația învechită - nu a funcționat. Textele conțineau atât de mult zgomot vizual și detalii inutile, încât reglementările și noul design erau neputincioși.
O mare parte din cele de mai sus vor fi determinate de platforma pe care o utilizați pentru documentare. De exemplu, avem Confluence. A trebuit să mă fac și eu cu el. Dacă sunteți interesat, citiți povestea dezvoltatorului nostru web: .
De unde să începeți să vă îmbunătățiți și cum să supraviețuiți
Dacă documentația ta este la fel de vastă ca cea a sistemului ISP și nu știi de unde să începi, începe cu cele mai mari probleme. Clienții nu înțeleg documentul - îmbunătățesc textele, fac regulamente, formează scriitori. Documentația este învechită - aveți grijă de procesele interne. Începeți cu cele mai populare articole despre cele mai populare produse: cereți asistență, uitați-vă la analiza site-ului și interogările din motoarele de căutare.
Să spunem imediat - nu va fi ușor. Și este puțin probabil să funcționeze rapid. Doar dacă nu ai început și faci ceea ce trebuie imediat. Un lucru pe care îl știm sigur este că se va îmbunătăți în timp. Dar procesul nu se va termina niciodată :-).
Sursa: www.habr.com