Dezvoltatori De ce nu treci peste documentație

În domeniul dezvoltării aplicațiilor mobile, aplicațiilor web, aplicațiilor desktop sau bibliotecilor JavaScript, documentația joacă un rol important care ar putea determina succesul dezvoltării software-ului. Dar dacă ați făcut vreodată o documentație, ați fi de acord cu mine că sunt lucrurile cele mai puțin favorabile pentru dezvoltatori.

Spre deosebire de codul de scriere (ceea ce dezvoltatorii s-au angajat să facă), documentația (pe care noi nu am făcut-o) trebuie și trebuie ușor digerată de toata lumea. Din punct de vedere tehnic, trebuie să traducem un limbaj al mașinii (codul) într-o limbă care este ușor de înțeles de oameni, ceea ce este mai dur decât sună.

Deși poate fi o sarcină dificilă, scrierea documentației este importantă și va aduce avantaje pentru utilizatorii dvs., colegii dvs. și în special pentru dvs..

Documentația bună ajută utilizatorii

Documentația ajută cititorul să înțeleagă cum funcționează un cod, evident. Dar mulți dezvoltatori fac greșeala de a presupune că utilizatorii software-ului vor fi competenți. Prin urmare, documentația poate fi material subțire, sărind peste multe elemente esențiale pe care ar fi trebuit să le conțină de la început. Dacă sunteți priceput în limbă, puteți să vă gândiți la lucrurile din proprie inițiativă; daca nu esti, atunci esti pierdut.

Documentația destinată utilizatorilor constă, de obicei, în utilizare practică sau în “cum să-”. Regula de bază atunci când creați documentația pentru utilizatorii generali este asta ar trebui să fie clar. Folosirea cuvintelor prietenoase cu oamenii este preferabilă termenilor tehnici sau jargonului. Exemplele de utilizare reală vor fi, de asemenea, foarte apreciate.

Un design bun de aspect ar ajuta, de asemenea, utilizatorii să scaneze prin fiecare secțiune a documentației, fără a afecta ochii. Câteva exemple bune (cunoscute ca "mele favorite") sunt documentația pentru Bootstrap și WordPress " “Primii pași cu WordPress”.

Aceasta ajută și alți dezvoltatori

Fiecare dezvoltator va avea propriul stil de codificare. Dar, atunci când este vorba de a lucra într-o echipă, vom avea de multe ori să împărtășim coduri cu ceilalți colegi de echipă. Deci, este esențial să au un consens cu privire la un standard pentru a păstra toată lumea pe aceeași pagină. O documentație corect scrisă ar fi referința pe care o are echipa

Dar spre deosebire de documentația utilizatorului final, această documentație descrie de obicei procedurile tehnice cum ar fi convenția de numire a codurilor, care arată modul în care ar trebui să fie construite paginile particulare și cum funcționează API împreună cu exemplele de cod. Adesea, ar trebui să scriem documentația în linie cu codul (cunoscut sub numele de comentarii) pentru a descrie ceea ce face codul.

În plus, în cazul în care aveți noi membri care se alătură echipa ta mai târziu, această documentație ar putea fi o modalitate eficientă de a le instrui, deci nu trebuie să le dați o rulare 1-pe-1 pe cod.

Ciudat, de asemenea, ajută Coder

Lucrul amuzant despre codificare este că uneori chiar și dezvoltatorii înșiși nu înțeleg codul pe care l-au scris. Acest lucru este valabil în special în cazurile în care codurile au fost lăsate neatinsă luni sau chiar ani.

O nevoie brusc de a revizui codurile dintr-un motiv sau altul ar lăsa pe cineva să se întrebe ce se întâmpla în mintea lor când au scris aceste coduri. Nu vă surprindeți: am mai fost în această situație. Aceasta este exact cand eu dorit Mi-am documentat corect codul.

Prin documentarea codurilor dvs., veți putea ajunge rapid în partea de jos a codurilor și fără frustrare, economisind o mare parte din timpul dvs. care poate fi cheltuit pentru a obține modificările în.

Ce face pentru o bună documentare?

Există mai mulți factori pentru a construi o documentație bună.

1. Să nu presupunem niciodată

Nu presupuneți că utilizatorii dvs. știu ce tu știți și ce ei vreau sa stiu. Este întotdeauna mai bună pentru a începe de la început indiferent de nivelul de competență al utilizatorilor.

Dacă ați construit un plugin jQuery, de exemplu, vă puteți inspira din documentația SlickJS. Acesta arată cum să structurați codul HTML, unde să plasați CSS și JavaScript, cum să inițializați pluginul jQuery la nivelul său cel mai de bază și chiar să arătați marcajul final complet după adăugarea tuturor acestor lucruri, ceea ce este ceva evident.

Linia de jos este că documentația este scrisă cu procesul de gândire al unui utilizator, nu al unui dezvoltator. Abordând documentația proprie în acest fel vă va oferi o perspectivă mai bună în organizarea piesei proprii.

2. Urmați standardul

În adăugarea documentației care merge în linie cu codul, utilizați standardul așteptat al limbii. Este întotdeauna o idee bună să descrieți fiecare funcție, variabilele, precum și valoarea returnată de funcție. Iată un exemplu de bună documentație inline pentru PHP.

 / ** * Adăugă clase personalizate la matricea claselor corpului. * * @param array $ classes Clase pentru elementul corpului. * @return array * / funcția body_classes ($ classes) // Adaugă o clasă de blog-grup în bloguri cu mai mult de 1 autor publicat. dacă (is_multi_author ()) $ classes [] = 'grup-blog';  returnează clase de $;  add_filter ('body_class', 'body_classes'); 

Următoarele sunt câteva referințe pentru formatarea documentației inline cu cele mai bune practici în PHP, JavaScript și CSS:

• PHP: Documentație standard PHP pentru WordPress
• JavaScript: UtilizațiJSdoc
• CSS: CSSDoc

Dacă utilizați SublimeText aș sugera să instalați DocBlockr care va pre-umple în mod inteligent codul dvs. cu documentația inline.

3. Elemente grafice

Utilizați elemente grafice, vorbesc mai bine decât text. Aceste suporturi sunt utile, mai ales daca construiti software cu interfata grafica. Puteți adăuga elemente de indicare, cum ar fi săgețile, cercul sau ceva care ar putea ajuta utilizatorii să-și dea seama unde să meargă pentru a realiza pașii, fără presupuneri.

Următoarele sunt un exemplu din aplicația Tower din care vă puteți inspira. Ei explică în mod eficient modul în care funcționează controlul versiunii într-un mod plăcut, ceea ce îl face mai ușor de înțeles decât utilizarea liniilor de comandă a textului simplu.

4. Secționarea

Puteți lua în considerare includerea câtorva lucruri în documentația din listele și tabelele cu marcatori, deoarece acest lucru face ca conținutul mai lung să fie mai ușor de scanat și citit de utilizatori.

Adăugați un tabel de conținut și împărțiți documentația în secțiuni ușor digerabile, păstrând totodată fiecare secțiune relevantă cu ceea ce urmează. Păstrați-l scurt și simplu. Mai jos este un exemplu de documentație bine organizată pe Facebook. Cuprinsul ne duce acolo unde vrem să sarăm într-un clic.

5. Revizuirea și actualizarea

În cele din urmă, examinați documentația pentru greșeli și revizuiți când este necesar sau ori de câte ori există modificări semnificative ale produsului, ale software-ului sau ale bibliotecii. Documentația dvs. nu ar fi utilă nimănui dacă nu este actualizată periodic alături de produsul dvs..