Kūrėjai Kodėl neturėtumėte praleisti dokumentacijos

Mobiliųjų programų, žiniatinklio programų, darbalaukio programų arba „JavaScript“ bibliotekų kūrimo srityje dokumentai vaidina svarbų vaidmenį, kuris galėtų lemti programinės įrangos kūrimo sėkmę. Bet jei kada nors atlikote dokumentaciją, su manimi sutinkate, kad tai yra daugiausiai mėgstamų dalykų kūrėjams.

Skirtingai nuo rašymo kodo (kuris yra tai, ką kūrėjai prisiregistravo), dokumentai (kuriuos mes neturėjome) turi būti ir turėtų būti lengvai supjaustyti Visi. Techniškai, mes turime išversti mašinos kalbą (kodą) į žmonėms suprantamą kalbą, kuri yra griežtesnė nei atrodo.

Nors dokumentai gali būti labai sunkūs, dokumentai yra svarbūs ir suteiks naudos jūsų vartotojams, kolegoms ir ypač sau.

Gera dokumentacija padeda vartotojams

Dokumentacija padeda skaitytojui suprasti, kaip veikia kodas, akivaizdu. Tačiau daugelis kūrėjų daro klaidą, manydami, kad programinės įrangos naudotojai bus kompetentingi. Taigi dokumentacija gali būti plona medžiaga, praleidžiant daugelį esminių dalykų, kuriuos ji turėjo turėti nuo pat pradžių. Jei esate išminties kalba, galite išsiaiškinti savo iniciatyva; jei nesate, tuomet jūs prarasite.

Naudotojams skirti dokumentai paprastai susideda iš praktinio naudojimo arba “kaip”. Nykščio taisyklė kuriant bendrųjų vartotojų dokumentaciją yra tokia ji turėtų būti aiški. Žmonėms palankių žodžių naudojimas yra geriau nei techniniai terminai ar žargonas. Tikro naudojimo pavyzdžiai taip pat bus labai vertinami.

Geras maketo dizainas taip pat padėtų vartotojams nuskaityti kiekvieną dokumentacijos dalį be akių. Keli geri pavyzdžiai (dar žinomi kaip mano mėgstamiausi) yra „Bootstrap“ ir „WordPress“ dokumentai. “Pirmieji žingsniai su „WordPress“”.

Ji padeda kitiems kūrėjams

Kiekvienas kūrėjas turės savo kodavimo stilių. Tačiau, kai kalbama apie darbą komandoje, dažnai turėsime dalytis kodais su kitais komandos nariais. Taigi tai yra būtina turėti konsensusą dėl standarto išlaikyti visus tame pačiame puslapyje. Tinkamai parašyta dokumentacija būtų nuoroda į komandos poreikius

Tačiau, skirtingai nei galutinio vartotojo dokumentai, šie dokumentai paprastai aprašomi technines procedūras kaip kodų pavadinimo konvencija, rodanti, kaip turi būti sukurti tam tikri puslapiai, ir kaip API veikia kartu su kodo pavyzdžiais. Dažnai mes taip pat turėtume parašyti dokumentus kartu su kodu (žinomas kaip komentarus) apibūdinti kodą.

Be to, jei turite naujų narių vėliau jūsų komanda, šis dokumentas gali būti veiksmingas būdas juos apmokyti, taigi jums nereikės suteikti 1-to-1 kodo.

Keista, tai taip pat padeda „Coder“

Juokingas dalykas apie kodavimą yra kartais net kūrėjai patys nesupranta kodo, kurį jie parašė. Tai ypač aktualu tais atvejais, kai kodai buvo palikti nepaliesti mėnesių ar net metų.

Staigus poreikis peržiūrėti kodus dėl vienos ar kitos priežasties paliktų vieną klausimą, kas vyksta jų protuose, kai jie parašė šiuos kodus. Nenustebkite: buvau šioje situacijoje. Tai yra tiksliai kada aš norėjo Aš tinkamai dokumentavau savo kodą.

Dokumentuodami savo kodus, galėsite greitai ir be nusivylimų patekti į savo kodų apačią, taupydami daug laiko, kurį galite išleisti norint gauti pakeitimus.

Kas daro gerą dokumentaciją?

Yra keletas veiksnių, galinčių sukurti gerą dokumentaciją.

1. Niekada Tarkime

Negalima manyti, kad jūsų naudotojai žinotų, ką tu taip pat žinokite ir ką jie Noriu žinoti. Tai visada geriau pradėti nuo pat pradžių nepriklausomai nuo naudotojų kvalifikacijos lygio.

Jei, pavyzdžiui, sukūrėte „jQuery“ papildinį, galite įkvėpti „SlickJS“ dokumentaciją. Jis parodo, kaip struktūrizuoti HTML, kur įdėti CSS ir „JavaScript“, kaip inicijuoti jQuery įskiepį pagrindiniame lygmenyje, ir netgi parodo visą galutinį žymėjimą po visų šių dalykų pridėjimo, o tai yra kažkas akivaizdus.

Esmė yra tai, kad dokumentai yra parašyti su vartotojo, o ne kūrėjo, minties procesu. Tokiu būdu artėjant savo dokumentams, galėsite geriau matyti savo kūrinį.

2. Sekite standartą

Pridedant dokumentą, kuris yra suderintas su kodu, naudoti iš kalbos tikėtiną standartą. Visada yra gera idėja apibūdinti kiekvieną funkciją, kintamuosius ir vertę, kurią grąžina funkcija. Čia yra geros inline dokumentacijos PHP pavyzdys.

 / ** * Įtraukia pasirinktines klases į kūno klases. * * @param masyvas $ klases Kūno elemento klasės. * @return array * / function body_classes ($ klases) // Prideda grupinių dienoraščių grupes į tinklaraščius, kuriuose yra daugiau nei 1 publikuotas autorius. jei (is_multi_author ()) $ class [] = 'group-blog';  grąžinti $ klases;  add_filter ('body_class', 'body_classes'); 

Toliau pateikiamos kelios nuorodos, kaip suformuluoti inline dokumentus su geriausia patirtimi PHP, JavaScript ir CSS:

• PHP: PHP dokumentacijos standartas WordPress
• „JavaScript“: UseJSDoc
• CSS: CSSDoc

Jei naudojate „SublimeText“, siūlau įdiegti „DocBlockr“, kuris protingai iš anksto užpildys jūsų kodą su inline dokumentacija.

3. Grafiniai elementai

Naudokite grafinius elementus, jie kalba geriau nei tekstas. Šios žiniasklaidos priemonės yra naudingos, ypač jei sukuriate programinę įrangą su grafine sąsaja. Galite pridėti nukreipimo elementus, pvz., Rodykles, apskritimą, arba viskas, kas gali padėti vartotojams išsiaiškinti, kur eiti, kad būtų galima atlikti veiksmus, be spėjimų.

Toliau pateikiamas pavyzdys iš „Tower“ programos, kurioje galite įkvėpti. Jie efektyviai paaiškina, kaip versijų valdymas veikia maloniai, todėl jį galima geriau suprasti nei naudojant paprastąsias teksto komandų eilutes.

4. Skirstymas

Galite apsvarstyti kelis dalykus į dokumentaciją įterpiant sąrašus ir lenteles, nes tai leidžia ilgesnį turinį lengviau nuskaityti ir skaityti vartotojams.

Pridėkite turinio lentelę ir padalinkite dokumentus lengvai virškinamuose skyriuose, tačiau palikite kiekvieną skyrių atitinkamą su tuo, kas ateina. Laikykite trumpą ir paprastą. Žemiau pateikiamas puikiai organizuoto dokumentacijos „Facebook“ pavyzdys. Turinys pateikia mums, kur norime pereiti prie paspaudimo.

5. Pakeiskite ir atnaujinkite

Galiausiai peržiūrėkite klaidų dokumentaciją ir, jei reikia, peržiūrėkite ir, kai yra reikšmingų produkto, programinės įrangos ar bibliotekos pakeitimų. Jūsų dokumentai niekam nebus naudingi, jei jie nebus reguliariai atnaujinami kartu su jūsų produktu.