Utvecklare Varför du inte ska hoppa över dokumentation

I utvecklingsområdet för mobilappar, webbapps, stationära appar eller JavaScript-bibliotek spelar dokumentation en viktig roll som kan avgöra mjukvarans utvecklingssucces. Men om du någonsin har gjort dokumentation, skulle du hålla med om att det är ganska mycket de minsta favorit sakerna för utvecklare att göra.

Till skillnad från skrivkod (vilket är det som utvecklarna anmält sig att göra), måste dokumentation (som vi inte), och bör lätt smältas av alla. Tekniskt måste vi översätta ett maskinspråk (kod) till ett språk som är förståeligt för människor, vilket är hårdare än det låter.

Även om det kan vara en reell belastning, är dokumentationen viktig och kommer att ge fördelar för dina användare, dina kollegor och speciellt dig själv.

Bra dokumentation hjälper användare

Dokumentation hjälper läsaren förstå hur en kod fungerar, självklart. Men många utvecklare gör misstaget att de antar att användarna av programvaran kommer att vara skickliga. Därefter kan dokumentationen vara tunn material och hoppa över mycket av de väsentliga saker som det borde ha inneburit från början. Om du är kunnig på språket kan du räkna ut saker på eget initiativ. Om du inte är så är du förlorad.

Dokumentation avsedd för användare består vanligen av praktisk användning eller “hur”. Tumregeln när du skapar dokumentation för allmänna användare är det det borde vara tydligt. Att använda människorvänliga ord föredras av tekniska termer eller jargong. Exempel på verklig användning kommer också att uppskattas.

En bra layoutdesign skulle också verkligen hjälpa användare att skanna igenom varje del av dokumentationen utan ögonbelastning. Några bra exempel (aka my favorites) är dokumentation för Bootstrap och WordPress ' “Första steget med WordPress”.

Det hjälper andra utvecklare också

Varje utvecklare kommer att ha sin egen kodningsstil. Men när det gäller att arbeta i ett lag, måste vi ofta dela koder med de andra lagkamraterna. Så det är viktigt att ha enighet om en standard för att hålla alla på samma sida. En korrekt skriftlig dokumentation skulle vara den referens som laget behöver

Men till skillnad från slutanvändardokumentation beskriver denna dokumentation vanligen tekniska förfaranden som kodnamnskonvention, som visar hur särskilda sidor ska byggas och hur API fungerar tillsammans med kodexemplen. Ofta måste vi också skriva dokumentationen inline med koden (känd som kommentarer) för att beskriva vad koden gör.

Dessutom, i det fall du har nya medlemmar gå med ditt lag senare kan den här dokumentationen vara ett effektivt sätt att träna dem, så du behöver inte ge dem en 1-till-1-körning på koden.

Konstigt hjälper det också Coder

Det roliga med kodning är det ibland även utvecklarna själva förstår inte koden som de har skrivit. Detta gäller särskilt om koderna har lämnats orörda i månader eller till och med år.

Ett plötsligt behov av att återvända koderna av en eller annan anledning skulle leda till att man undrade vad som hände i deras sinnen när de skrev dessa koder. Bli inte förvånad: Jag har varit i denna situation tidigare. Detta är exakt när jag önskade Jag hade dokumenterat min kod korrekt.

Genom att dokumentera dina koder kommer du snabbt och frustrerande att komma till botten av dina koder vilket sparar mycket tid som kan användas för att få förändringarna i.

Vad gör för god dokumentation?

Det finns flera faktorer att bygga en bra del av dokumentationen.

1. Antag aldrig

Antag inte att dina användare vet vad du vet så bra som vad de vill veta. Det är alltid bättre att börja från början oberoende av användarnas kompetensnivå.

Om du till exempel har byggt ett jQuery-plugin kan du få inspiration från SlickJSs dokumentation. Den visar hur man strukturerar HTML-koden, var du ska placera CSS och JavaScript, hur du initierar jQuery-pluginet på sin mest grundläggande nivå och visar även den fullständiga slutliga markeringen efter att ha lagt till alla dessa saker, vilket är något uppenbart.

Grunden är att dokumentationen är skriven med en användares tankeprocess, inte en utvecklare. Närmar sig din egen dokumentation så kommer du att få ett bättre perspektiv när du organiserar din egen bit.

2. Följ Standard

När du lägger till dokumentation som går i linje med koden, använd förväntad standard för språket. Det är alltid en bra idé att beskriva varje funktion, variablerna, samt det värde som returneras av funktionen. Här är ett exempel på bra inline-dokumentation för PHP.

 / ** * Lägger till anpassade klasser i arrayen av kroppsklasser. * * @param array $ classes Klasser för kroppselementet. * @return array * / function body_classes ($ classes) // Lägger till en grupp av gruppbloggar till bloggar med mer än 1 publicerad författare. om (is_multi_author ()) $ classes [] = 'group-blog';  returnera $ klasser;  add_filter ('body_class', 'body_classes'); 

Nedan följer några referenser för att formatera inline-dokumentation med bästa praxis i PHP, JavaScript och CSS:

• PHP: PHP Dokumentation Standard för WordPress
• JavaScript: AnvändJSDoc
• CSS: CSSDoc

Om du använder SublimeText skulle jag föreslå att du installerar DocBlockr som klokt förfyller din kod med inline-dokumentation.

3. Grafiska element

Använd grafiska element, de talar bättre än text. Dessa medier är användbara, särskilt om du bygger programvara med grafiskt gränssnitt. Du kan lägga till pekelement som pilar, cirkel eller allt som kan hjälpa användarna att räkna ut var man ska gå för att utföra stegen utan gissning.

Följande är ett exempel från tornet app där du kan dra inspiration från. De förklarar effektivt hur versionskontroll fungerar på ett tilltalande sätt som gör det mer förståeligt än att använda vanlig textkommandolinjer.

4. Sektionering

Du kan överväga att lägga in några saker i dokumentationen i punktlistor och tabeller, eftersom det här gör att längre innehåll blir lättare att skanna och läsa för användare.

Lägg till en tabell med innehåll och dela dokumentationen i lätt smältbara sektioner, men ändå hålla varje avsnitt relevant med vad som kommer nästa. Håll det kort och enkelt. Nedan är ett exempel på snyggt organiserad dokumentation på Facebook. Innehållsförteckningen tar oss där vi vill hoppa till med ett klick.

5. Ändra och uppdatera

Slutligen granska dokumentationen för misstag och revidera vid behov eller och när det finns väsentliga ändringar av produkten, programvaran eller biblioteket. Din dokumentation skulle inte vara till nytta för någon om inte uppdateras regelbundet tillsammans med din produkt.