Razvojni programeri Zašto ne biste trebali preskočiti dokumentaciju

U području razvoja mobilnih aplikacija, web-aplikacija, desktop aplikacija ili JavaScript knjižnica, dokumentacija igra važnu ulogu koja bi mogla odrediti uspjeh razvoja softvera. Ali ako ste ikada napravili dokumentaciju, složili bi se sa mnom da je to zapravo najmanje omiljena stvar za programere.

Za razliku od kodova za pisanje (što su programeri potpisali), dokumentacija (koju nismo) mora i mora biti lako probavljena svatko. Tehnički, moramo prevesti strojni jezik (kod) u jezik koji je razumljiv ljudima, što je teže nego što zvuči.

Iako to može biti stvarno opterećenje, pisanje dokumentacije je važno i donijet će prednosti vašim korisnicima, vašim kolegama, a posebno vama.

Dobra dokumentacija pomaže korisnicima

Dokumentacija pomaže čitatelju razumjeti kako radi kod, očito. No, mnogi programeri čine pogrešku pretpostavljajući da će korisnici softvera biti stručnjaci. Prema tome, dokumentacija može biti tanak materijal, preskočivši mnogo bitnih stvari koje je trebala sadržavati od početka. Ako ste pametni u jeziku, možete shvatiti stvari na vlastitu inicijativu; ako niste, onda ste izgubljeni.

Dokumentacija namijenjena korisnicima obično se sastoji od praktične uporabe ili “kako da”. To je pravilo pri izradi dokumentacije za opće korisnike to bi trebalo biti jasno. Korištenje riječi prilagođenih ljudima bolje je od tehničkih izraza ili žargona. Primjeri stvarne upotrebe također će biti visoko cijenjeni.

Dobar dizajn dizajna također bi stvarno pomogao korisnicima skenirati kroz svaki dio dokumentacije bez naprezanja očiju. Nekoliko dobrih primjera (poznatiji kao moji favoriti) su dokumentacija za Bootstrap i WordPress “Prvi koraci s WordPressom”.

To također pomaže drugim razvojnim programerima

Svaki će programer imati vlastiti stil kodiranja. No, kada je riječ o radu u timu, često ćemo morati dijeliti kodove s drugim suigračima. Stoga je bitno imati konsenzus o standardu zadržati sve na istoj stranici. Odgovarajuća pisana dokumentacija trebala bi biti referenca koju tim treba

No, za razliku od dokumentacije krajnjeg korisnika, ova dokumentacija obično opisuje tehnički postupci kao što je konvencija imenovanja koda, koja pokazuje kako bi određene stranice trebale biti izgrađene i kako API funkcionira zajedno s primjerima koda. Često bismo također morali pisati dokumentaciju u skladu s kodom (poznat kao komentari) opisati što radi kod.

Osim toga, u slučaju gdje imate pridruživanje novih članova kasnije, ova dokumentacija može biti vremenski učinkovit način za njihovo osposobljavanje, tako da im ne morate dati 1-na-1.

Čudno je također pomoći koderu

Smiješno je kodiranje ponekad čak i sami programeri ne razumiju kod koji su napisali. To je osobito istinito u slučajevima kada su kodovi ostali netaknuti mjesecima ili čak godinama.

Iznenadna potreba za ponovnim razmatranjem kodova iz jednog ili drugog razloga ostavila bi čovjeka da se zapita što se događa u njihovim mislima kad su napisali ove kodove. Nemojte se iznenaditi: već sam bio u ovoj situaciji. Ovo je precizno kada ja želio Svoj sam kod ispravno dokumentirao.

Dokumentiranjem vaših kodova moći ćete brzo i bez frustracija doći do dna kodova, štedeći vam puno vremena koje možete potrošiti na izmjene.

Što čini dobru dokumentaciju?

Postoji nekoliko čimbenika za izgradnju dobre dokumentacije.

1. Nikada nemojte pretpostavljati

Nemojte pretpostavljati da vaši korisnici znaju što vas znati kako i što oni želim znati. Uvijek je bolje početi od samog početka bez obzira na stupanj stručnosti korisnika.

Ako ste, primjerice, izgradili jQuery dodatak, možete uzeti inspiraciju iz SlickJSove dokumentacije. Pokazuje kako strukturirati HTML, gdje staviti CSS i JavaScript, kako inicijalizirati jQuery plugin na njegovoj najosnovnijoj razini, pa čak i pokazati kompletnu konačnu oznaku nakon dodavanja svih ovih stvari, što je nešto očito..

Donja crta je dokumentacija napisana s procesom razmišljanja korisnika, a ne programera. Približavanje vlastitoj dokumentaciji na ovaj način pružit će vam bolju perspektivu u organiziranju vlastitog djela.

2. Slijedite Standard

Dodavanjem dokumentacije koja je u skladu s kodom, koristite standard koji se očekuje od jezika. Uvijek je dobra ideja opisati svaku funkciju, varijable, kao i vrijednost koju vraća funkcija. Ovdje je primjer dobre inline dokumentacije za PHP.

 / ** * Dodaje prilagođene klase nizu klasa tijela. * * @param array $ class Klase za element tijela. * @return array * / function body_classes ($ classes) // Dodaje klasu grupnog bloga blogovima s više od 1 objavljenog autora. if (is_multi_author ()) $ class [] = 'grupni blog';  return $ classes;  add_filter ('body_class', 'body_classes'); 

Slijedi nekoliko referenci za oblikovanje inline dokumentacije s najboljim praksama u PHP-u, JavaScriptu i CSS-u:

• PHP: PHP Dokumentacija Standard za WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

Ako koristite SublimeText predložio bih da instalirate DocBlockr koji će pametno unaprijed napuniti vaš kod pomoću inline dokumentacije.

3. Grafički elementi

Koristite grafičke elemente, oni govore bolje od teksta. Ovi mediji dolaze u korisne, osobito ako gradite softver s grafičkim sučeljem. Možete dodati elemente za pokazivanje kao što su strelice, krug ili sve što može pomoći korisnicima da shvate kamo treba ići kako bi ostvarili korake, bez nagađanja.

Slijedi primjer iz aplikacije Tower gdje možete izvući inspiraciju. Oni učinkovito objašnjavaju kako kontrola verzije radi na ugodan način što ga čini razumljivijim od upotrebe običnog tekstualnog naredbenog retka.

4. Odvajanje

Razmislite o umatanju nekoliko stvari u dokumentaciju u popisima i tablicama s oznakama, jer to olakšava skeniranje i čitanje duljeg sadržaja za korisnike.

Dodajte sadržajnu tablicu i podijelite dokumentaciju u lako probavljivim odjeljcima, ali zadržite svaki odjeljak relevantnim s onim što slijedi. Neka bude kratka i jasna. U nastavku je primjer lijepo organizirane dokumentacije na Facebooku. Sadržaj nas vodi do mjesta na koje želimo skočiti jednim klikom.

5. Revizija i ažuriranje

Naposljetku pregledajte dokumentaciju zbog grešaka i po potrebi ih revidirajte ili, i kad god dođe do značajnih promjena proizvoda, softvera ili knjižnice. Vaša dokumentacija nikome ne bi bila od koristi, ako se ne ažurira redovito uz vaš proizvod.