La documentació del programari és només un conjunt d'articles. Però fins i tot ells et poden tornar boig. En primer lloc, passeu molt de temps buscant les instruccions necessàries. Llavors entens el text fosc. Fas com està escrit, però el problema no està resolt. Busques un altre article, et poses nerviós... Una hora després abandones tot i te'n vas. Així és com funciona la mala documentació. Què fa que sigui així i com solucionar-ho: llegiu sota el tall.
Hi havia moltes mancances en la nostra documentació antiga. Fa gairebé un any que l'estem reelaborant perquè l'escenari descrit anteriorment no afecti als nostres clients. mira, и .
Problema 1: articles poc clars i mal escrits
Si la documentació és impossible d'entendre, quin sentit té? Però ningú escriu articles incomprensibles a propòsit. Passen quan l'autor no pensa en el públic i el propòsit, aboca aigua i no revisa el text per detectar errors.
- El públic. Abans d'escriure un article, cal pensar en el nivell de preparació del lector. És lògic que en un article per a un principiant no s'ha de saltar els passos bàsics i deixar termes tècnics sense explicació, però en un article sobre una característica rara que només necessiten els professionals, s'ha d'explicar el significat de la paraula PHP.
- Objectiu. Una cosa més a pensar amb antelació. L'autor ha de marcar un objectiu clar, determinar l'efecte útil de l'article i decidir què farà el lector després de llegir-lo. Si això no es fa, acabaràs amb una descripció pel bé de la descripció.
- Aigua i insectes. Hi ha molta informació innecessària i burocràcia, errors i errors ortogràfics interfereixen amb la percepció. Encara que el lector no sigui un nazi de gramàtica, la negligència en el text el pot apagar.
Tingueu en compte els consells anteriors i els articles seran més clars, garantits. Per fer-ho encara millor, utilitzeu el nostre .
Problema 2. Els articles no responen a totes les preguntes
És dolent quan la documentació no segueix el desenvolupament, no respon a preguntes reals i els errors que hi ha no es corregeixen durant anys. Són problemes no tant de l'autor, sinó de l'organització dels processos dins de l'empresa.
La documentació no segueix el desenvolupament
La funció ja està en publicació, el màrqueting té previst cobrir-la i, aleshores, resulta que el nou article o traducció encara no està a la documentació. Fins i tot vam haver de posposar l'estrena per això. Podeu demanar a tothom que lliuri les tasques als escriptors tècnics a temps tant com vulgueu, però no funcionarà. Si el procés no està automatitzat, la situació es repetirà.
Hem fet canvis a YouTrack. La tasca d'escriure un article sobre una característica nova recau en l'escriptor tècnic en el mateix moment en què es comença a provar la funció. Aleshores, el màrqueting n'aprèn per preparar-se per a la promoció. Les notificacions també arriben al missatger corporatiu de Mattermost, de manera que és simplement impossible perdre's notícies dels desenvolupadors.
La documentació no reflecteix les sol·licituds dels usuaris
Estem acostumats a treballar així: va sortir una característica, n'hem parlat. Hem descrit com activar-lo, apagar-lo i fer ajustos precisos. Però, què passa si un client utilitza el nostre programari d'una manera que no esperàvem? O té errors que no hem pensat?
Per garantir que la documentació sigui el més completa possible, recomanem analitzar les sol·licituds d'assistència, les preguntes en fòrums temàtics i les consultes als motors de cerca. Els temes més populars es transferiran als escriptors tècnics perquè puguin complementar els articles existents o escriure-ne de nous.
La documentació no s'està millorant
És difícil fer-ho perfectament de seguida, encara hi haurà errors. Podeu esperar comentaris dels clients, però és poc probable que denuncien cada error ortogràfic, inexactitud, article incomprensible o no trobat. A més dels clients, els empleats llegeixen la documentació, la qual cosa significa que veuen els mateixos errors. Això es pot utilitzar! Només cal crear condicions en les quals sigui fàcil informar d'un problema.
Tenim un grup al portal intern on els empleats deixen comentaris, suggeriments i idees sobre documentació. El suport necessita un article, però no existeix? El verificador es va adonar de la imprecisió? El soci s'ha queixat als responsables de desenvolupament dels errors? Tots en aquest grup! Els escriptors tècnics arreglen algunes coses immediatament, en transfereixen algunes a YouTrack i donen a altres una estona per pensar-hi. Per evitar que el tema s'acabi, de tant en tant us recordem l'existència del grup i la importància del feedback.
Problema 3. Es necessita molt de temps per trobar l'article adequat.
Un article que no es pot trobar no és millor que un article que no es pot trobar. El lema d'una bona documentació hauria de ser "Fàcil de cercar, fàcil de trobar". Com aconseguir-ho?
Organitzar l'estructura i determinar el principi per triar els temes. L'estructura ha de ser tan transparent com sigui possible perquè el lector no pensi: "On puc trobar aquest article?" En resum, hi ha dos enfocaments: des de la interfície i des de les tasques.
- Des de la interfície. El contingut duplica les seccions del panell. Aquest era el cas de l'antiga documentació del sistema ISP.
- De tasques. Els títols dels articles i seccions reflecteixen les tasques dels usuaris; Els títols gairebé sempre contenen verbs i respostes a la pregunta "com fer-ho". Ara passem a aquest format.
Sigui quin sigui l'enfocament que trieu, assegureu-vos que el tema sigui rellevant per al que cerquen els usuaris i que es tracta d'una manera que abordi específicament la pregunta de l'usuari.
Configura una cerca centralitzada. En un món ideal, la cerca hauria de funcionar fins i tot quan us equivoqueu o cometeu un error amb l'idioma. La nostra recerca a Confluence fins ara no ens pot agradar amb això. Si teniu molts productes i la documentació és general, adapteu la cerca a la pàgina on es troba l'usuari. En el nostre cas, la cerca a la pàgina principal funciona per a tots els productes, i si ja esteu en una secció específica, només per als articles que hi ha.
Afegiu contingut i pa ratllat. És bo quan cada pàgina té un menú i mitges de pa: el camí de l'usuari a la pàgina actual amb la possibilitat de tornar a qualsevol nivell. A l'antiga documentació del sistema ISP, calia sortir de l'article per accedir al contingut. Era inconvenient, així que ho vam arreglar al nou.
Col·loqueu enllaços al producte. Si la gent acudeix a donar suport una i altra vegada amb la mateixa pregunta, té sentit afegir una pista amb la seva solució a la interfície. Si teniu dades o informació sobre quan un usuari té un problema, també podeu notificar-los amb una llista de correu. Mostreu-los preocupació i traieu la càrrega del suport.
A la dreta de la finestra emergent hi ha un enllaç a un article sobre la configuració de DNSSEC a la secció de gestió de dominis d'ISPmanager
Configureu referències creuades dins de la documentació. Els articles que estiguin relacionats entre ells haurien d'estar "enllaçats". Si els articles són seqüencials, assegureu-vos d'afegir fletxes cap endavant i cap enrere al final de cada text.
El més probable és que una persona primer vagi a buscar una resposta a la seva pregunta no a tu, sinó a un motor de cerca. És una llàstima que no hi hagi enllaços a la documentació per motius tècnics. Així que tingueu cura de l'optimització de motors de cerca.
Problema 4. El disseny obsolet interfereix amb la percepció
A més dels textos dolents, la documentació es pot fer malbé pel disseny. La gent està acostumada a llegir materials ben escrits. Blocs, xarxes socials, mitjans de comunicació: tot el contingut no només es presenta bonic, sinó també fàcil de llegir i agradable a la vista. Per tant, podeu entendre fàcilment el dolor d'una persona que veu text com a la captura de pantalla següent.
Hi ha tantes captures de pantalla i aspectes destacats en aquest article que no ajuden, sinó que només interfereixen amb la percepció (es pot fer clic a la imatge)
No hauríeu de fer una lectura llarga de la documentació amb un munt d'efectes, però heu de tenir en compte les regles bàsiques.
Disseny. Determineu l'amplada del text del cos, el tipus de lletra, la mida, els encapçalaments i el farciment. Contracteu un dissenyador i, per acceptar el treball o fer-ho vosaltres mateixos, llegiu el llibre "Tipografia i maquetació" d'Artyom Gorbunov. Presenta només una vista del disseny, però és bastant suficient.
Dotacions. Determina què requereix èmfasi en el text. Normalment es tracta d'una ruta a la interfície, botons, insercions de codi, fitxers de configuració, blocs "Tingueu en compte". Determineu quines seran les assignacions d'aquests elements i registreu-les a la normativa. Tingueu en compte que com menys descàrrega, millor. Quan n'hi ha molts, el text és sorollós. Fins i tot les cometes generen soroll si s'utilitzen massa sovint.
Captures de pantalla. Acordeu amb l'equip en quins casos calen captures de pantalla. Definitivament no cal il·lustrar cada pas. Un gran nombre de captures de pantalla, incl. botons separats, interfereixen amb la percepció, fan malbé el disseny. Determineu la mida, així com el format dels ressaltats i les signatures de les captures de pantalla, i registreu-les a la normativa. Recordeu que les il·lustracions sempre han de correspondre al que està escrit i ser rellevants. De nou, si el producte s'actualitza regularment, serà difícil fer un seguiment de tothom.
Longitud del text. Eviteu articles massa llargs. Dividiu-los en parts i, si això no és possible, afegiu contingut amb enllaços d'ancoratge al començament de l'article. Una manera senzilla de fer que un article sigui visualment més curt és ocultar els detalls tècnics que necessita un cercle reduït de lectors sota un spoiler.
Formats. Combina diversos formats als teus articles: text, vídeo i imatges. Això millorarà la percepció.
No intenteu tapar problemes amb un disseny bonic. Sincerament, nosaltres mateixos esperàvem que l'"embolcall" estalviés la documentació obsoleta; no va funcionar. Els textos contenien tant soroll visual i detalls innecessaris que la normativa i el nou disseny eren impotents.
Gran part de l'anterior serà determinat per la plataforma que utilitzeu per a la documentació. Per exemple, tenim Confluència. Jo també vaig haver de jugar amb ell. Si us interessa, llegiu la història del nostre desenvolupador web: .
Per on començar a millorar i com sobreviure
Si la vostra documentació és tan extensa com la del sistema ISP i no saps per on començar, comença pels problemes més grans. Els clients no entenen el document: milloren els textos, fan reglaments, formen escriptors. La documentació no està actualitzada: tingueu cura dels processos interns. Comenceu amb els articles més populars sobre els productes més populars: demaneu assistència, consulteu l'anàlisi del lloc i consultes als motors de cerca.
Diguem-ho de seguida: no serà fàcil. I tampoc és probable que funcioni ràpidament. A menys que estiguis començant i facis el correcte de seguida. Una cosa que sabem del cert és que millorarà amb el temps. Però el procés no s'acabarà mai :-).
Font: www.habr.com
