Razvijalci Zakaj ne smete preskočiti dokumentacije

V razvojnem področju mobilnih aplikacij, spletnih aplikacij, namiznih aplikacij ali knjižnic JavaScripta ima dokumentacija pomembno vlogo, ki lahko določi uspešnost razvoja programske opreme. Ampak, če ste kdaj naredili dokumentacijo, bi se strinjali z mano, da je to kar najmanj priljubljenih stvari za razvijalce.

Za razliko od pisanja kode (to je tisto, kar so razvijalci podpisali), mora dokumentacija (ki je nismo) preprosto prebaviti vsem. Tehnično moramo prevesti strojni jezik (kodo) v jezik, ki je razumljiv človeku, kar je težje, kot se zdi..

Čeprav je lahko resnično obremenjujoče, je pisanje dokumentacije pomembno in bo prineslo prednosti za vaše uporabnike, vaše kolege in še posebej za vas.

Dobra dokumentacija pomaga uporabnikom

Dokumentacija pomaga bralcu razumeti, kako deluje koda, očitno. Toda mnogi razvijalci naredijo napako, če predpostavljajo, da bodo uporabniki programske opreme dobro obvladali. Zato je dokumentacija lahko tanek material, ki preskoči veliko bistvenih elementov, ki bi jih moral vsebovati že od začetka. Če ste pametni v jeziku, lahko ugotovite stvari na lastno pobudo; če niste, potem ste izgubljeni.

Dokumentacija, namenjena uporabnikom, je ponavadi praktična ali uporabna “kako”. To je pravilo pri ustvarjanju dokumentacije za splošne uporabnike treba je jasno določiti. Uporaba človeku prijaznih besed je boljša od tehničnih izrazov ali žargona. Pravi primeri uporabe bodo prav tako zelo cenjeni.

Dobra postavitev bi uporabnikom prav tako pomagala pri skeniranju skozi vsak del dokumentacije brez obremenitve oči. Nekaj ​​dobrih primerov (tudi mojih priljubljenih) so dokumentacija za Bootstrap in WordPress. “Prvi koraki z WordPressom”.

To pomaga tudi drugim razvijalcem

Vsak razvijalec bo imel svoj stil kodiranja. Toda, ko gre za delo v ekipi, bomo pogosto morali deliti kode z ostalimi kolegi. Zato je nujno soglasje o standardu da bi vsi ostali na isti strani. Ustrezno pisna dokumentacija bi bila referenca, ki jo ekipa potrebuje

Za razliko od dokumentacije za končnega uporabnika ta dokumentacija navadno opisuje tehničnih postopkov kot je konvencija o poimenovanju kod, ki prikazuje, kako naj se izdelajo določene strani, in kako API deluje skupaj s primeri kode. Pogosto bi morali vnesti tudi dokumentacijo s kodo (znano kot komentarjev), da opišete, kaj počne koda.

Poleg tega, v primeru, kjer imate pridružitev novih članov kasneje, je ta dokumentacija lahko časovno učinkovit način za njihovo usposabljanje, tako da vam ni treba dati 1-na-1.

Nenavadno je tudi, da pomaga Coder

Smešna stvar pri kodiranju je včasih celo razvijalci sami ne razumejo kode, ki so jo napisali. To še posebej velja za primere, v katerih kodeksi ostajajo nedotaknjeni mesece ali celo leta.

Nenadna potreba po ponovnem pregledu kode iz enega ali drugega razloga bi pustila, da se sprašujete, kaj se dogaja v njihovih mislih, ko so napisali te kode. Ne bodite presenečeni: prej sem bil v tej situaciji. To je natančno ko jaz želel Pravilno sem dokumentiral svojo kodo.

Z dokumentiranjem vaših kod boste lahko hitro in brez frustracij prišli do dna kod, s čimer boste prihranili veliko časa, ki ga lahko porabite za spremembe v.

Kaj naredi za dobro dokumentacijo?

Obstaja več dejavnikov, ki ustvarijo dober dokument.

1. Nikoli ne prevzemite

Ne domnevajte, da vaši uporabniki vedo kaj vas vedeti, kot tudi kaj oni želeli vedeti. Vedno je bolje začeti od samega začetka ne glede na stopnjo strokovnosti uporabnikov.

Če ste na primer zgradili vtičnik jQuery, lahko v dokumentaciji SlickJS-a vzamete navdih. Prikazuje, kako strukturirati HTML, kam postaviti CSS in JavaScript, kako inicializirati vtičnik jQuery na najosnovnejši ravni in celo prikazati celotno končno oznako po dodajanju vseh teh stvari, kar je nekaj očitnega.

Na koncu je dokumentacija napisana z miselnim procesom uporabnika, ne razvijalca. Približevanje lastni dokumentaciji na ta način vam bo dalo boljšo perspektivo pri organizaciji lastnega dela.

2. Sledite standardu

Pri dodajanju dokumentacije, ki je skladna s kodo, uporabite standard, ki se pričakuje od jezika. Vedno je dobra ideja opisati vsako funkcijo, spremenljivke in vrednost, ki jo funkcija vrne. Tukaj je primer dobre inline dokumentacije za PHP.

 / ** * Doda razrede po meri v niz telesnih razredov. * * @param array $ classi Razredi za element telesa. * @return array * / function body_classes ($ classes) // Doda razred skupinskih blogov v bloge z več kot 1 objavljenim avtorjem. if (is_multi_author ()) $ classes [] = 'blog skupine';  return $ classes;  add_filter ('body_class', 'body_class'); 

V nadaljevanju je nekaj referenc za oblikovanje inline dokumentacije z najboljšimi praksami v PHP, JavaScript in CSS:

• PHP: Dokumentacijski standard PHP za WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

Če uporabljate SublimeText, predlagam, da namestite DocBlockr, ki bo pametno vnaprej zapolnil kodo z vgrajeno dokumentacijo.

3. Grafični elementi

Uporabite grafične elemente, govorijo bolje kot besedilo. Ti mediji so uporabni, zlasti če gradite programsko opremo z grafičnim vmesnikom. Dodate lahko elemente, kot so puščice, krog ali vse, kar lahko uporabnikom pomaga ugotoviti, kam naj gredo, da bi izvedli korake, brez ugibanja.

Spodaj je primer iz aplikacije Tower, kjer lahko črpate navdih. Učinkovito pojasnijo, kako nadzor nad različicami deluje na prijeten način, zaradi česar je bolj razumljiv kot uporaba ukaznih vrstic z navadnim besedilom.

4. Razdelitev

Razmislite o zavijanju nekaj stvari v dokumentacijo v seznamih in tabelah, ki so označene z oznakami..

Dodajte tabelo vsebine in razdelite dokumentacijo v lahko prebavljive odseke, hkrati pa ohranite vsak odsek pomemben s tem, kar je naslednje. Naj bo kratek in preprost. Spodaj je primer lepo organizirane dokumentacije na Facebooku. Kazalo nas pripelje na mesto, kjer želimo skočiti na klik.

5. Revizija in posodobitev

Nazadnje preglejte dokumentacijo zaradi napak in jih po potrebi popravite ali in kadar koli pride do pomembnih sprememb izdelka, programske opreme ali knjižnice. Vaša dokumentacija ne bi bila nikomur uporabna, če se redno ne posodablja poleg vašega izdelka.