Un manual despre scrierea unei documentații bune

Această postare a fost contribuită de autorul invitat Jeff Matson. Jeff este șeful documentației pentru GravityForms. El este creatorul pluginului WordPress Heartbeat Control și este un fan al anilor 90.

De multe ori, documentația este cea mai subestimată parte a procesului de dezvoltare. Când ne uităm la vedetele rock din comunitatea WordPress, de obicei ne uităm la dezvoltatori, designeri și marketeri. Se știu puține despre autorii de documentare care și-au vărsat sângele, transpirația și lacrimile pentru a se asigura că totul merge bine.

Această postare este despre cei care se uită zi de zi la linii nesfârșite de cod pentru a descifra ceea ce gândea dezvoltatorul și adevăratul sens din spatele codului care există.

O documentare bună este mai mult decât cuvinte

Scriitorii de documentație buni oferă mai mult decât un manual de instrucțiuni, ei oferă o experiență. Am cunoscut documentari excelenți, începători instruiți, iar cea mai mare diferență dintre ei este înțelegerea creierului celor care îl citesc. La fel ca un roman, documentarea are un flux care menține cititorul interesat și ingerează mai multe informații decât își dau seama.

Documentația de calitate vizează utilizatorii care sunt cel mai probabil să o citească. De asemenea, oferă un punct de referință pentru cei care este mai puțin probabil să-l citească. De exemplu, dacă documentezi un anumit cârlig, de obicei se presupune că un dezvoltator îl va citi, dar ce zici de cei care au puțină experiență în dezvoltare?

Un bun redactor de documentație va oferi un punct de referință pentru cei care au nevoie de un impuls în direcția corectă, fără a fi nevoie să contacteze asistența pentru a le explica.

Documentația are un impact mai mare decât credeți

Cei mai mulți pur și simplu ignoră documentația, împingând-o în abisul nesfârșit până când nu mai pot suporta. Sunt vinovat de același lucru în unele cazuri. Ceea ce acești oameni nu realizează, este că în fiecare moment în care pluginul sau tema lor este lăsată nedocumentată, experiența utilizatorului are de suferit.

Să aruncăm o privire la cel mai frecvent bilet de asistență. Dacă ai documenta mai bine această problemă, acele bilete ar dispărea complet? Probabil ca nu. Ați primi mai puține bilete cu privire la problemă și ați crește productivitatea dvs. sau a agentului dvs. de asistență? O garantez. Cred că toți am putea folosi mai puține bilete de asistență.

După cum am menționat anterior, documentația are un impact dramatic asupra experienței utilizatorului. Dacă utilizatorul este capabil să găsească informațiile cu ușurință și eficient, el și-a economisit atât timp cât și al tău. Speranța medie de viață la nivel mondial este de 66,57 ani, iar utilizatorii dvs. ar prefera să facă altceva cu viața lor decât să se joace cu documentația prost scrisă.

Dacă un client vede că ai depus destul timp și efort în documentația ta, te va aprecia, fie conștient sau nu, mai bine. O documentație bună arată că îți pasă de ele după vânzarea inițială.

Ați fost vreodată lăsat în stare de uscătură după ce ați cheltuit banii câștigați din greu și ați regretat curând achiziția? Cred că toți avem. Cu o documentație adecvată, puteți evita transmiterea acestui sentiment clienților dvs.

Cum poți scrie o documentație mai bună?

Primul pas este să nu o mai evitați. Odată ce ești bun la asta, scrierea documentației este mai mult o experiență plăcută decât crezi. De fapt, va deveni a doua natură. La fel ca orice altceva în lume, practica face perfectă.

Unul dintre primii pași pe care doriți să-i faceți atunci când decideți să vă duceți documentația la nivelul următor este să vă determinați punctele dureroase. Despre ce ești contactat? Dacă începi să scrii orbește despre lucruri, s-ar putea să descoperi că ceea ce scrii nu are atât de mult impactul pe care l-ai dori.

Una dintre cele mai bune tehnici pe care le-am descoperit este de a urmări numărul de bilete care sunt documentate față de cele care nu sunt și de a le împărți în categorii pe cele care nu sunt. În acest fel, vă puteți viza mai bine punctele dureroase și puteți revizui părțile care ar putea să nu fie atât de utile pe cât ar trebui să fie.

După ce ați determinat ce documentație ar trebui să scrieți, ar trebui să vă determinați publicul țintă și să îl împărțiți în dezvoltatori, utilizatori și utilizatori cu putere. Acest lucru vă ajută să vă adresați unui anumit public. Vom analiza mai târziu cum să-i vizam pe acești utilizatori.

Apoi, doriți să descompuneți documentul. Pentru dezvoltatori, veți dori să o descompuneți în informații brute (argumente acceptate, valori returnate etc.), exemple specifice și cazuri de utilizare. Pentru utilizatori, cel mai bun curs de acțiune este o explicație. Fiecare pas pe care vor trebui să-l facă, indiferent de cât de banal ar părea, este critic.

Spune-le la fiecare pas. Documentarea pentru utilizatorii cu putere este foarte asemănătoare cu un scenariu de utilizator, dar mai structurată și mai poate fi scanată. Fii clar, dar permite-le să sară cu ușurință acolo unde trebuie să meargă fără a citi mai întâi pasul anterior.

Arta de a scrie o documentare mai bună

Când vine vorba de arta de a-ți scrie documentația, scrie într-un mod care să țintească cel mai bine publicul tău, dar folosește și un limbaj simplu pe care știi că îl vor înțelege. Unul dintre cele mai bune motive pentru aceasta se datorează traducerilor. În timp ce Google Translate face o treabă excelentă, este mult mai ușor să traduci vocabularul simplu al unui elev de clasa a 5-a decât cel conținut într-o teză de licență.

În conținutul dvs., nu vă fie teamă să trimiteți linkuri către conținut relevant. Acest lucru vă va permite să evitați să vă repetați prin mai multe documente, precum și să permiteți cititorului să revină dacă are nevoie de mai multe informații despre un anumit subiect. La urma urmei, obiectivele tale principale sunt să faci utilizatorul fericit și să economisești timp.

Procesul de documentare nu se oprește după ce apăsați butonul de publicare . Reveniți și revizuiți fiecare document după cum este necesar. Aproape imediat după publicarea documentului, întoarceți-vă și vedeți dacă biletele de asistență pe care le-ați urmărit au scăzut și dacă traficul către acel articol a crescut. De obicei, dacă obțineți mai mult trafic către un articol, este de ajutor. Dacă primiți mai mult trafic, dar același număr de bilete de asistență, vă recomandăm să vă uitați la articolul respectiv pentru a vedea de ce.

Ce am învățat

În primul rând, sper că, după ce ați ajuns până aici, să aveți o apreciere mai bună pentru cei din tranșee care scriu documentația pe care cei mai mulți dintre noi o considerăm de la sine înțeles. Este cu adevărat o formă de artă pe care mulți dintre noi, cei care scriem documente pentru a-și câștiga existența, îi place cu adevărat și în care dedică multe, multe ore.

De asemenea, sper că veți renunța la acest articol gândindu-vă mai mult la documentația dvs. existentă și la modul în care poate fi îmbunătățită. Documentarea corectă poate fi extrem de plină de satisfacții și, odată pusă în practică, poate fi de fapt destul de distractiv de scris.

Documentează-te devreme, documentează-te des. Un produs grozav este mai mult decât un cod grozav, este, de asemenea, frumos documentat.