Udviklere, hvorfor du ikke bør springe over dokumentation

I udviklingsområdet for mobilapps, webapps, desktopapps eller JavaScript-biblioteker spiller dokumentation en vigtig rolle, der kan bestemme softwareens udviklingssucces. Men hvis du nogensinde har lavet dokumentation, vil du være enig med mig i, at det er stort set de mindst foretrukne ting for udviklere at gøre.

I modsætning til skrive kode (hvilket er udviklerne tilmeldt sig at gøre), skal dokumentation (som vi ikke) skal og skal let fordøjes af alle sammen. Teknisk er vi nødt til at oversætte et maskinsprog (kode) til et sprog, der er forståeligt for mennesker, hvilket er hårdere end det lyder.

Selv om det kan være en reel byrde, er dokumentationen vigtig og vil give fordele for dine brugere, dine kolleger og især dig selv.

God dokumentation hjælper brugere

Dokumentation hjælper læseren forstå, hvordan en kode fungerer, naturligvis. Men mange udviklere begår fejlen ved at antage, at brugerne af softwaren vil være dygtige. Dokumentationen kan derfor være tyndt materiale, idet man lægger meget af det væsentlige, som det burde have indeholdt fra starten. Hvis du er kyndig på sproget, kan du finde ud af ting på eget initiativ; hvis du ikke er det, så går du tabt.

Dokumentation beregnet til brugere består normalt af praktisk anvendelse eller “hvordan”. Tommelfingerregelen, når du opretter dokumentation til generelle brugere, er det det skal være klart. Brug af menneskevenlige ord foretrækkes til tekniske udtryk eller jargon. Eksempler på reel brug vil også blive meget værdsat.

Et godt layoutdesign ville også virkelig hjælpe brugere med at scanne gennem hvert afsnit af dokumentationen uden øjenbelastning. Et par gode eksempler (også mine favoritter) er dokumentation for Bootstrap og WordPress ' “Første skridt med WordPress”.

Det hjælper andre udviklere også

Hver udvikler vil have deres egen kodestil. Men når det kommer til at arbejde i et hold, skal vi ofte dele koder med de andre holdkammerater. Så det er vigtigt at have enighed om en standard at holde alle på samme side. En korrekt skriftlig dokumentation vil være den reference, som holdet har brug for

Men i modsætning til slutbrugerdokumentation beskriver denne dokumentation typisk tekniske procedurer lignende kode-navngivningskonvention, der viser, hvordan bestemte sider skal konstrueres, og hvordan API'et fungerer sammen med kodeeksemplerne. Ofte skal vi også skrive dokumentationen inline med koden (kendt som kommentarer) for at beskrive, hvad koden laver.

Derudover, i tilfælde af hvor du har Nye medlemmer tiltræder dit team senere, denne dokumentation kan være en tidseffektiv måde at træne dem på, så du behøver ikke give dem en 1-til-1 kørsel ned på koden.

Mærkeligt det hjælper også Coder

Det sjove ved kodning er det nogle gange selv udviklerne selv forstår ikke koden, de har skrevet. Dette gælder især i tilfælde, hvor koderne er blevet uberørt i måneder eller endog år.

Et pludseligt behov for at revidere koderne af en eller anden grund ville lade sig undre over, hvad der foregik i deres sind, da de skrev disse koder. Vær ikke overrasket: Jeg har været i denne situation før. Dette er præcist når jeg ønsket Jeg havde dokumenteret min kode korrekt.

Ved at dokumentere dine koder kan du hurtigt og uden frustration komme til bunden af ​​dine koder, hvilket sparer dig meget af din tid, der kan bruges til at få ændringer i.

Hvad der gør for god dokumentation?

Der er flere faktorer at opbygge et godt stykke dokumentation.

1. Antag aldrig

Antag ikke, at dine brugere ved hvad du ved så godt som hvad de vil vide. Det er altid bedre at starte fra begyndelsen uanset brugerens færdighedsniveau.

Hvis du f.eks. Har opbygget et jQuery-plugin, kan du tage inspiration fra SlickJS's dokumentation. Det viser, hvordan man strukturerer HTML, hvor man skal sætte CSS og JavaScript, hvordan man initialiserer jQuery-pluginet på sit mest grundlæggende niveau og endda viser det komplette endelige markup efter at have tilføjet alle disse ting, hvilket er noget indlysende.

Hovedlinjen er dokumentationen er skrevet med en brugeres tankeproces, ikke en udvikler. Nærmer din egen dokumentation på denne måde vil give dig et bedre perspektiv ved at organisere dit eget stykke.

2. Følg standarden

Ved at tilføje dokumentation, der går i linje med koden, brug den forventede standard af sproget. Det er altid en god ide at beskrive hver funktion, variablerne og den værdi, der returneres af funktionen. Her er et eksempel på god inline dokumentation til PHP.

 / ** * Tilføjer brugerdefinerede klasser til gruppen af ​​kropsklasser. * * @param array $ classes Klasser for kropselementet. * @return array * / function body_classes ($ klasser) // Tilføjer en gruppe af gruppeblog til blogs med mere end 1 offentliggjort forfatter. if (is_multi_author ()) $ classes [] = 'group-blog';  returnere $ klasser;  add_filter ('body_class', 'body_classes'); 

Nedenstående er et par referencer til formatering af inline-dokumentation med bedste praksis i PHP, JavaScript og CSS:

• PHP: PHP Documentation Standard for WordPress
• JavaScript: BrugJSDoc
• CSS: CSSDoc

Hvis du bruger SublimeText, foreslår jeg at installere DocBlockr, der vil prefyldiggøre din kode med inline dokumentation.

3. Grafiske elementer

Brug grafiske elementer, de taler bedre end tekst. Disse medier er nyttige, især hvis du opbygger software med grafisk interface. Du kan tilføje punktelementer som pile, cirkel eller Alt, hvad der kan hjælpe brugerne med at finde ud af, hvor de skal gå for at udføre trinene, uden gætteri.

Følgende er et eksempel fra Tårn-appen, hvor du kan trække inspiration fra. De forklarer effektivt, hvordan versionskontrol fungerer på en behagelig måde, der gør det mere forståeligt end at bruge almindelige tekstkommandolinjer.

4. Sektionering

Du kan overveje at indpakke nogle få ting i dokumentationen inden for punktlister og tabeller, da dette gør længere indhold lettere at scanne og læse for brugere.

Tilføj en indholdsfortegnelse og opdel dokumentationen i let fordøjelige sektioner, men alligevel holde hver sektion relevant med hvad der kommer næste. Hold det kort og ligetil. Nedenfor er et eksempel på pænt organiseret dokumentation i Facebook. Indholdsfortegnelsen tager os hvor vi vil hoppe til i et klik.

5. Revider og opdater

Endelig skal du gennemgå dokumentationen for fejl og revidere, når det er nødvendigt, og og når der er væsentlige ændringer af produktet, softwaren eller biblioteket. Din dokumentation vil ikke være til nytte for nogen, hvis de ikke opdateres regelmæssigt sammen med dit produkt.