Documentarea pluginurilor și temelor WordPress

Publicat: 2017-03-17

Documentarea este ceva ce de obicei este apreciat doar atunci când există o problemă și ai nevoie de răspunsuri rapid. În acest articol, vom analiza motivele pentru care scrierea documentației pentru activele dvs. WordPress este importantă pentru practica dvs. ca dezvoltator WordPress și pentru calitatea temelor și a pluginurilor pe care le livrați.

De ce este importantă documentarea?

Păstrarea unui set actualizat de documentație despre proiectele, activele sau produsele dvs. este importantă din multe motive.

În primul rând, este o experiență obișnuită să te uiți la ceva pe care l-ai făcut acum 2 luni și nu te-ai atins de atunci și să nu ai idee ce înseamnă. Când îl dezvoltați, aveți totul în cap, dar această înțelegere nu va mai exista în viitor. Așadar, fie folosind comentarii de cod în linie, fie scrierea notițelor text simplu în Markdown, vă ajută să vă salvați viitorul de confuzie.

În al doilea rând, păstrarea activelor documentate este utilă pentru alți dezvoltatori WordPress. Și acest lucru are sens chiar dacă ești un freelancer singuratic (sunt obligat să colaborezi cu alți oameni la un moment dat). Fie vor trebui să folosească acele active, fie li se va cere să le întrețină și/sau să le actualizeze. Este foarte frustrant să folosești cod nedocumentat care este scris de altcineva, care nu este prin preajmă pentru a oferi asistență sau a explica unele părți dificile.

În cele din urmă, documentația adaugă acel aspect „lustruit” produselor tale, iar clienții tăi te vor iubi mai mult.

5 principii pentru o documentare eficientă

Scrierea tehnică este o disciplină în sine și este folosită pentru a comunica informații tehnice într-o manieră clară și lipsită de ambiguitate. (Fără a se limita doar la computere, avocații și medicii, de exemplu, folosesc și propriul limbaj tehnic). Din acest motiv, un document care este considerat scriere tehnică urmează de obicei un anumit stil și se supune unui set de reguli.

Să trecem prin cele mai importante 5 astfel încât să poți scrie documentație eficientă pentru produsele tale!

Preferă să folosești mai puține cuvinte decât ai folosi în mod normal în scris: fiecare cuvânt ar trebui să aibă un scop. Fii direct și simplu. Documentarea este de obicei căutată atunci când o persoană are probleme și dorește să găsească rapid o soluție. De exemplu, o propoziție precum „Eșecul de a distruge Obiectul Q va introduce scurgeri de memorie” este de preferat decât „Eșecul de a distruge Obiectul Q va cauza introducerea de scurgeri de memorie”.
Prefer să folosiți vocea activă în loc de pasivă: „ Faceți clic pe butonul din dreapta sus” în loc de „Butonul din dreapta sus trebuie să fie apăsat ”. Folosirea unei voci active elimină orice ambiguitate cu privire la cine face ce. Vocea pasivă este folosită numai atunci când trebuie să vă concentrați pe obiect, mai degrabă decât pe subiect (de exemplu, Platforma Pressidium este construită având în vedere securitatea ) .
Folosiți un limbaj descriptiv atunci când trebuie să descrieți concepte și imperativ când trebuie să descrieți o procedură pas cu pas (cum ar fi tutorialele).
Folosiți liste cu marcatori atunci când trebuie să enumerați lucruri care nu au ordine și liste numerotate când ordinea punctelor este semnificativă.
Asigurați-vă că ați testat singur instrucțiunile, înainte de a le prezenta!

Documentarea pluginurilor WordPress

Pluginurile WordPress sunt ca orice alt program. Ele oferă o anumită funcționalitate, necesită instalare și uneori și depanare. Indiferent cât de simple sunt, este întotdeauna o idee bună să oferiți o cantitate adecvată de documentație, deoarece nu toți utilizatorii au aceeași expertiză tehnică.

Publicarea pluginului dvs. WordPress pe wordpress.org vă va oferi un loc pentru a pune instrucțiuni de instalare, capturi de ecran, Întrebări frecvente chiar și un jurnal de modificări! Completarea acestora cu informații utile și de calitate este esențială pentru ca pluginul dvs. să devină mai popular:

Scrieți o descriere convingătoare și utilă care, în cele din urmă, va face utilizatorul să vă descarce pluginul și să vă viziteze site-ul web.
Adăugați capturi de ecran adnotate care explică fiecare element de configurare al pluginului dvs. în plus față de cele care arată cum arată pluginul dvs. în browser.
Pune întrebări în Întrebări frecvente care nu sunt banale. O modalitate bună de a descoperi cazuri de margine ciudate este să ceri unui prieten care nu cunoaște computerul să folosească pluginul.
Aveți un jurnal de modificări actualizat și bine scris. Frazele concise și criptice sunt un mare nu și arată că nu vă pasă cu adevărat de utilizatorii dvs.
Asigurați-vă că codul pluginului dvs. este bine comentat și urmează cele mai bune practici software și standardele oficiale de codare.

Dacă sunteți blocat și aveți nevoie de puțină inspirație, faceți o mică cercetare și vedeți cum este scris textul în plugin-uri populare care au sute de mii de instalări, în comparație cu cele mai puțin utilizate.

Documentarea temelor WordPress

Documentarea temelor WordPress este o chestiune complet diferită. Cea mai frecventă problemă cu temele WordPress este să nu știi ce secțiune corespunde cu ce element vizual. Nu toată lumea vorbește fluent CSS:

Creați o ierarhie a tuturor secțiunilor CSS-ului dvs., cu descrierile corespunzătoare.
Pentru fiecare secțiune, adăugați o captură de ecran adnotată care detaliază fiecare funcționalitate, împreună cu un mic exemplu. Nu uitați să folosiți vocea activă și limbajul imperativ, atunci când arătați cum să faceți ceva care impune utilizatorului să urmeze instrucțiunile.
Utilizați un instrument precum css_doc pentru a vă ajuta. Acest lucru generează un stil de documentație JavaDoc și poate fi publicat.
Uneori, comentariile de cod nu sunt suficiente și trebuie să creați un document Ghid de stil pentru tema dvs. CSS. Documentele ghidului de stil descriu cum trebuie să arate elementele și în ce cazuri trebuie utilizate. Ele impun consecvența și facilitează, de asemenea, colaborarea. Vedeți acest exemplu de la Google.
Utilizați un cadru CSS precum Blueprint CSS. Acest lucru vă va ajuta în dezvoltare, oferindu-vă un set de instrumente, cum ar fi o grilă personalizabilă, o tipografie implicită care funcționează, resetarea CSS a browserului și multe altele.
Din nou, nu uitați să consultați standardele oficiale de codare CSS WordPress.