Utviklere Hvorfor du ikke bør hoppe over dokumentasjon

I utviklingsområdet for mobilapper, webapps, stasjonære apper eller JavaScript-biblioteker spiller dokumentasjon en viktig rolle som kan bestemme utviklingssuksessen for programvaren. Men hvis du noen gang har gjort dokumentasjon, vil du være enig med meg om at det er ganske mye de minste favorittene for utviklere å gjøre.

I motsetning til skrivingskode (som utviklerne har meldt seg på å gjøre), må dokumentasjon (som vi ikke gjorde), og bør lett fordøyes av alle. Teknisk må vi oversette et maskinspråk (kode) til et språk som er forståelig for mennesker, noe som er tøffere enn det høres ut.

Selv om det kan være veldig tungt å skrive, er dokumentasjonen viktig og vil gi fordeler for brukerne, dine kolleger og spesielt deg selv.

God dokumentasjon hjelper brukerne

Dokumentasjon hjelper leseren forstå hvordan en kode fungerer, åpenbart. Men mange utviklere gjør feilen ved å anta at brukerne av programvaren vil være dyktige. Dermed kan dokumentasjonen være tynt materiale, og hopper over mye av det som burde ha vært inneholdt fra begynnelsen. Hvis du er kunnskapsrik på språket, kan du finne ut ting på eget initiativ; Hvis du ikke er det, er du tapt.

Dokumentasjon beregnet for brukere består vanligvis av praktisk bruk eller “hvordan”. Tommelfingerregelen når du lager dokumentasjon for generelle brukere, er det det burde være klart. Bruk av menneskevennlige ord er å foretrekke for tekniske termer eller jargong. Eksempler på ekte bruk vil også bli verdsatt.

En god layoutdesign vil også virkelig hjelpe brukerne å skanne gjennom hver del av dokumentasjonen uten øyebelastning. Noen gode eksempler (aka mine favoritter) er dokumentasjon for Bootstrap og WordPress ' “Første trinn med WordPress”.

Det hjelper andre utviklere også

Hver utvikler vil ha sin egen kodestil. Men når det gjelder å jobbe i et lag, må vi ofte dele koder med de andre lagkameratene. Så det er viktig å ha enighet om en standard å holde alle på samme side. En riktig skriftlig dokumentasjon vil være referansen teamet trenger

Men i motsetning til sluttbrukerdokumentasjonen, beskriver denne dokumentasjonen vanligvis tekniske prosedyrer som kodenavnekonvensjon, som viser hvordan bestemte sider skal bygges, og hvordan API-en fungerer sammen med kodeeksemplene. Ofte må vi også skrive dokumentasjonen inline med koden (kjent som kommentarer) for å beskrive hva koden gjør.

I tillegg, i tilfelle der du har nye medlemmer blir med teamet ditt senere, denne dokumentasjonen kan være en tidseffektiv måte å trene dem på, så du trenger ikke å gi dem en 1-mot-1-nedkjøring på koden.

Merkelig det hjelper også Coder

Den morsomme tingen om koding er det noen ganger selv utviklerne selv forstår ikke koden de har skrevet. Dette gjelder spesielt i tilfeller der kodene er blitt uberørt i måneder eller til og med år.

Et plutselig behov for å revidere kodene av en eller annen grunn, ville la en lure på hva som foregikk i deres sinn når de skrev disse kodene. Ikke bli overrasket: Jeg har vært i denne situasjonen før. Dette er presist når jeg ønsket Jeg hadde dokumentert koden min riktig.

Ved å dokumentere kodene dine, vil du kunne komme til bunnen av kodene raskt og uten frustrasjon, noe som sparer mye tid du kan bruke til å få endringene i.

Hva gjør for god dokumentasjon?

Det er flere faktorer som bygger en god del dokumentasjon.

1. Anta aldri

Ikke anta at brukerne vet hva du vet så vel som hva de ønsker å vite. Det er alltid bedre å starte fra begynnelsen uavhengig av brukerens ferdighetsnivå.

Hvis du har bygget et jQuery-plugin, kan du for eksempel ta inspirasjon fra SlickJSs dokumentasjon. Det viser hvordan du strukturerer HTML, hvor du skal sette CSS og JavaScript, hvordan du initialiserer jQuery-pluginet på sitt mest grunnleggende nivå, og viser til og med den endelige sluttoppdateringen etter å ha lagt til alle disse tingene, noe som er noe tydelig.

Bunnlinjen er dokumentasjonen er skrevet med en brukeres tankeprosess, ikke en utvikler. Nærmer din egen dokumentasjon på denne måten vil gi deg et bedre perspektiv ved å organisere ditt eget stykke.

2. Følg standarden

Ved å legge til dokumentasjon som går i tråd med koden, bruk standarden som forventes av språket. Det er alltid en god ide å beskrive hver funksjon, variablene, samt verdien returnert av funksjonen. Her er et eksempel på god inline-dokumentasjon for PHP.

 / ** * Legger til egendefinerte klasser i en rekke kroppsklasser. * * @param array $ classes Klasser for kroppselementet. * @return array * / function body_classes ($ classes) // Legger til en gruppe av gruppeblogg til blogger med mer enn 1 publisert forfatter. hvis (is_multi_author ()) $ classes [] = 'group-blog';  returner $ klasser;  add_filter ('body_class', 'body_classes'); 

Følgende er noen referanse for formatering av inline-dokumentasjon med beste praksis i PHP, JavaScript og CSS:

• PHP: PHP Dokumentasjon Standard for WordPress
• Javascript: BrukJSDoc
• CSS: CSSDoc

Hvis du bruker SublimeText, foreslår jeg at du installerer DocBlockr som vil pre-populere koden din med inline dokumentasjon.

3. Grafiske elementer

Bruk grafiske elementer, de snakker bedre enn tekst. Disse mediene kommer til nytte, spesielt hvis du bygger programvare med grafisk grensesnitt. Du kan legge til pekelementer som piler, sirkel eller alt som kan hjelpe brukerne til å finne ut hvor de skal gå for å utføre trinnene, uten gjetning.

Følgende er et eksempel fra tårnapplikasjonen hvor du kan tegne inspirasjon fra. De forklarer effektivt hvordan versjonskontroll fungerer på en behagelig måte som gjør det mer forståelig enn å bruke vanlig tekstkommandolinjer.

4. Seksjonering

Du kan vurdere å pakke inn noen få ting i dokumentasjonen i punktlister og tabeller, da dette gjør at lengre innhold er lettere å skanne og lese for brukere.

Legg til en tabell med innhold og del dokumentasjonen i lett fordøyelige seksjoner, men hold hver del relevant med det som kommer neste. Hold det kort og grei. Nedenfor er et eksempel på pent organisert dokumentasjon på Facebook. Innholdsfortegnelsen tar oss der vi ønsker å hoppe til med et klikk.

5. Revidere og oppdatere

Til slutt, gjennomgå dokumentasjonen for feil og revidere når det er nødvendig, eller og når det er betydelige endringer i produktet, programvaren eller biblioteket. Din dokumentasjon vil ikke være til nytte for noen hvis det ikke oppdateres regelmessig ved siden av produktet.