Documentație de produs pentru profesioniștii WordPress

Publicat: 2017-07-28

Documentația de produs este de obicei văzută ca nesemnificativă, că puteți tăia colțuri. Nu este văzut ca ceva care poate oferi valoare clientului sau ca ceva care ar putea afecta domenii cheie de afaceri, cum ar fi veniturile și marketingul. Desigur, ca profesionist WordPress nu va trebui să scrieți documentație în același mod ca Atlassian sau Cisco. De obicei, atunci când oamenii se gândesc la „documentare”, ei evocă imagini cu ghiduri groase, tipărite, indexate alfabetic pe un raft foarte mare pe care nimeni nu îl citește niciodată.

Dar asta s-a schimbat:

Odată cu apariția Agile și DevOps, software-ul de livrare a devenit mai rapid și ciclul de dezvoltare a devenit, de asemenea, mai dinamic. Și, ca rezultat, documentația reflectă acum starea actuală în cea mai nouă versiune, în loc să fie ceva static scris pe hârtie pentru totdeauna. Documentația este integrată în ciclul de dezvoltare și este actualizată la fel de frecvent ca și software-ul.

De ce ar trebui profesioniștilor WordPress să le pese de documentația produsului?

Documentația utilă și actualizată nu numai că ușurează viața utilizatorilor dvs., dar adaugă și un nivel de lustruire care devine un activ de marketing ca nimeni altul. Dimpotrivă, documentarea slabă are un impact negativ. Probabil că ați experimentat și dvs. acest lucru: ați avut o problemă pentru care încercați din greu să găsiți soluția în documentație și, când nu ați făcut-o, ați ajuns frustrat (și probabil supărat). Se agravează doar dacă plătiți pentru produs.

Dacă lucrați la o agenție WordPress, furnizarea de documentație în toate domeniile unui proiect, de la proiectarea inițială până la active, va adăuga un nivel de profesionalism care arată că:

Acordați atenție detaliilor.
Îți pasă de clientul tău suficient de mult încât să faci eforturi suplimentare.
Sunteți transparent și încrezător în ceea ce privește designul și deciziile de proiect tehnice.

Mike Puterbaugh, VP de marketing la MindTouch a scris un articol Mashable în care descrie cele 5 motive pentru care documentația produsului dumneavoastră este un activ de marketing. El a concluzionat cu următoarele:

Nu este o întreprindere sexy, dar îți va câștiga respectul colegilor tăi, un management mai eficient al companiei și o echipă mai colaborativă. Pentru că nu este vorba despre acest trimestru sau anul acesta, ci mai degrabă, este vorba despre afectarea avantajului competitiv și a creșterii pe termen lung.

Acum că am stabilit suficientă motivație, vom:

Explorați diferitele tipuri de documentație de produs care sunt relevante pentru WordPress.
Discutați nevoile fiecărui tip de documentație și oferiți sfaturi utile.
Oferiți câteva îndrumări inițiale despre cum puteți planifica și colabora la documentația produsului. Mai ales dacă lucrezi la o agenție WordPress.

Tipuri de documentație de produs WordPress

Un produs WordPress nu este doar despre pluginuri și teme. În această secțiune, vom discuta și despre ajutorul online, API-urile REST și un lucru curios numit microconținut.

Pluginuri WordPress

Documentația pluginului WordPress trebuie să răspundă pentru două mulțimi: utilizatori și dezvoltatori. Nevoile de documentare ale fiecăruia sunt diferite, la fel ca și stilul de scriere folosit.

Utilizatori

Nevoile de documentare ale utilizatorilor se învârt în principal în jurul depanării și configurării. Adăugați la aceasta că trebuie să vă prezentați pluginul într-o manieră atractivă, astfel încât utilizatorii să-l încerce. Fiecare plugin are propria sa pagină pe piața de pluginuri WordPress. Țineți cont de următoarele puncte:

Scrieți o descriere convingătoare și utilă care încurajează descărcarea și utilizarea.
Adăugați capturi de ecran adnotate din pagina de configurare a pluginului Dashboard cu descrieri.
Pune întrebări în întrebările frecvente care sunt utile și nu banale.
Aveți un jurnal de modificări actualizat și bine scris. Nu adăugați acolo note criptice sau concise.

Trebuie să vă amintiți că atunci când utilizatorii folosesc documentația, probabil că sunt grăbiți și nerăbdători să găsească o soluție. Scrieți clar, simplu și concis. Nu le face mai greu decât este deja.

Dezvoltatori

Pe lângă cele mai bune practici software și standardele oficiale de codare PHP, ar trebui să vă concentrați atenția asupra următoarelor domenii:

cârlige pentru pluginuri

Acestea fac munca de modificare a comportamentului WordPress. Foarte probabil, pluginul dvs. WordPress le folosește. Deoarece cârligele pentru pluginuri sunt o parte importantă a codului, ar trebui să documentați cum le utilizați și în ce funcții WordPress sunt implicate.

etichete șablon

Etichetele șablonului reprezintă o altă modalitate prin care un plugin WordPress poate îmbunătăți funcționalitatea. Documentați funcțiile etichetei șablon pe care le-ați scris. Includeți exemple despre modul în care alți utilizatori sau dezvoltatori pot folosi etichetele pe site-ul lor WordPress.

Opțiuni

Opțiunile sunt o modalitate de a stoca anumite informații într-o bază de date WordPress. Acest lucru se face prin funcțiile add_option și get_options. În acest caz, documentați parametrii pe care îi transmiteți acestor funcții.

Bază de date

Pluginurile citesc și scriu frecvent o mulțime de lucruri diferite dintr-o bază de date. Deoarece acestea sunt operațiuni fundamentale, documentarea acestora va ajuta foarte mult alți dezvoltatori să înțeleagă cum funcționează pluginul dvs.

Teme WordPress

Există două zone diferite în care puteți crea documentație pentru teme. Primul este fișierele sursă. Fișierele CSS comentate sunt mai ușor de înțeles și de citit decât cele fără. Utilizați un instrument precum css_doc pentru a vă ajuta. Acest lucru generează un stil de documentație JavaDoc și poate fi publicat:

Cealaltă zonă este Ghidurile de stil. Aceste documente descriu cum trebuie să arate elementele și în ce cazuri trebuie utilizate. Ele impun consecvența și facilitează, de asemenea, colaborarea. Puteți citi articolul Hubspot cu 20 de exemple uimitoare de ghiduri de stil de brand, deoarece conține o mulțime de exemple grozave.

Din nou, nu uitați să consultați standardele oficiale de codare CSS WordPress.

Documentarea elementelor de design atât de detaliat ajută și la integrarea noilor angajați dacă sunteți o agenție WordPress. Ghidurile de stil pot fi folosite ca tutoriale sau materiale de referință pentru munca clienților noi și anterioare.

Ajutor online

Deoarece ajutorul online vizează rezolvarea unei anumite probleme ale utilizatorului, să începeți cu o listă de sarcini și probleme comune este calea de urmat. Deși lista la început nu va fi exhaustivă, fă-ți timp pentru a produce cât mai multe articole concrete. Ideea este să scrieți un fișier de ajutor online pentru fiecare dintre aceste sarcini și probleme și să le faceți un hyperlink la informații aferente. Puteți crea călătorii ale utilizatorilor pentru a mapa diferitele căi pe care un utilizator poate să le urmeze și să le facă în cadrul aplicației dvs. Explorarea e-mailurilor de asistență pentru a observa întrebări frecvente și zone problematice este o modalitate bună de a vă menține baza de cunoștințe actualizată și utilă.

Barry J. Rosenberg, autorul cărții Spring into Technical Writing oferă următoarele sfaturi pentru a scrie fișiere de ajutor bune:

Păstrați fiecare fișier de ajutor cât mai scurt posibil. Preferați listele numerotate în detrimentul listelor cu marcatori. Nu vă îndepărtați, nu nota de subsol și nu doriți. Păstrați fiecare fișier de ajutor concentrat pe o singură sarcină discretă.

Microconținut

Microconținutul are două definiții: prima fiind conținut precum titluri și secțiuni pe care utilizatorii le parcurg, pentru a obține esența unui anumit articol. Al doilea sunt fragmente mici de conținut care pot sta singure și sunt folosite pentru a îmbunătăți experiența utilizatorului. Un exemplu excelent pe care îl avem în minte este bitul „mai multe persoane tastează...” al lui Slack. (deși Slack este plin de microconținut scris excelent).

Acest bit se declanșează atunci când mai mult de 3 persoane tastează simultan pe același canal. În loc să imprime doar o listă de oameni care introduc în prezent, Slack ia această informație plictisitoare și îi adaugă puțină distracție. Discuția începe să devină foarte fierbinte și se vede. Este un exemplu excelent al modului în care documentația produsului (mesajele aplicației fac parte din asta, nu?) îi face pe oameni să vorbească despre tine (și creează meme hilare ca cele de mai sus).

API-ul REST

Documentarea API-urilor REST este o artă separată în sine. Ca și în cazul tuturor scrierilor tehnice, ar trebui să urmăriți concizia, claritatea și simplitatea definițiilor. Deoarece API-urile REST au propriul format și complexități, nu ați putea face mai rău decât să studiați ghidul excelent pentru documentarea API-urilor de Tom Johnson pe blogul său I'd Rather Be Writing.

Colaborarea și planificarea documentației

În cele din urmă, documentația ar trebui să facă parte din proiectarea produsului. Ca atare, ar trebui să îl abordați ca având o conductă suplimentară în ciclul software. Aceasta înseamnă utilizarea depozitelor de software pentru a stoca cea mai recentă versiune a documentației, utilizarea instrumentelor de urmărire a erorilor/problemelor pentru a monitoriza sarcinile și problemele, includerea planificarii proiectelor de documentare în foaia de parcurs și, nu în ultimul rând, colaborarea cu alte persoane. O schiță aproximativă a modului de a începe ar putea fi următoarea:

Înregistrați tot ceea ce utilizatorul ar dori să știe, precum și zonele pentru care va trebui să scrieți text.
Odată ce ai totul, grupează-le în categorii și formează titlurile documentelor.
Scrieți o specificație pentru fiecare document care detaliază lucruri precum titlul, descrierea, publicul țintă, media (ce formă va avea documentul), lungimea, cât timp va dura etc.
Adăugați estimările din specificațiile documentației la planificarea proiectului.

Deoarece documentația de produs se referă la toate domeniile, este aproape sigur că va trebui să lucrați cu diferiți oameni din cadrul organizației. Este o idee bună să vă așezați și să convineți asupra unui fel de proces despre cum vor decurge toate acestea. Ca în fiecare proiect, ar trebui să identificați părțile interesate care vor oferi asistență tehnică, precum și pe cei care vor revizui și edita modificările.

Ar trebui să existe diferite etape ale procesului. Acestea ar trebui să stabilească locul în care se strâng informațiile, când este redactat documentul, când este gata pentru corecturi literare, pentru comentarii tehnice, publicare și altele. Accentuați pe diferența dintre comentariile literare, tehnice și legate de conținut. De exemplu, nu este cu adevărat util atunci când îi ceri unui lider de echipă să comenteze documentul tău și în loc de informații legate tehnic, primești strigăte pentru gramatică și punctuație.

Închidere

Documentația produsului este un atu care se plătește pe termen lung. Oferă valoare clientului tău. S-ar putea chiar să fie atât de bun, cum ar fi documentația API-ului Stripe, de exemplu, încât oamenii se bucură de asta pe forumuri. Acest lucru generează implicarea și promovează marca și produsul dvs. într-un mod natural și puternic. Când este cuplat cu microconținutul creativ, realizează ceea ce înseamnă Mike Puterbaugh când spune că documentația produsului este „arma secretă a marketingului”.