Ontwikkelaars Waarom u documentatie niet overslaat

In het ontwikkelingsdomein van mobiele apps, webapps, desktop-apps of JavaScript-bibliotheken speelt documentatie een belangrijke rol die het ontwikkelingssucces van de software zou kunnen bepalen. Maar als je ooit documentatie hebt gedaan, ben je het met mij eens dat het vrijwel de minst favoriete dingen zijn die ontwikkelaars kunnen doen.

In tegenstelling tot het schrijven van code (wat is wat ontwikkelaars hebben aangemeld), documentatie (die we niet hebben) moet en moet gemakkelijk worden verteerd door iedereen. Technisch gezien moeten we een machinetaal (code) vertalen in een taal die voor mensen begrijpelijk is, wat moeilijker is dan het klinkt.

Hoewel het een lastige bezigheid kan zijn, is het schrijven van de documentatie belangrijk en levert het voordelen op voor uw gebruikers, uw collega's en vooral uzelf.

Goede documentatie helpt gebruikers

Documentatie helpt de lezer begrijp hoe een code werkt, duidelijk. Maar veel ontwikkelaars maken de fout om ervan uit te gaan dat de gebruikers van de software bekwaam zullen zijn. Vandaar dat de documentatie dun materiaal kan zijn en veel van de essenties overslaat die het vanaf het begin had moeten bevatten. Als je verstandig bent in de taal, kun je dingen uitzoeken op eigen initiatief; als je dat niet bent, ben je verloren.

Documentatie bestemd voor gebruikers bestaat meestal uit praktisch gebruik of de “hoe”. De vuistregel bij het maken van documentatie voor algemene gebruikers is dat het moet duidelijk zijn. Het gebruik van mensvriendelijke woorden verdient de voorkeur boven technische termen of jargon. Echte gebruiksvoorbeelden zullen ook zeer op prijs worden gesteld.

Een goed lay-outontwerp zou ook echt helpen gebruikers om elk deel van de documentatie te scannen zonder oogbelasting. Een paar goede voorbeelden (ook bekend als mijn favorieten) zijn documentatie voor Bootstrap en WordPress ' “Eerste stappen met WordPress”.

Het helpt ook andere ontwikkelaars

Elke ontwikkelaar heeft zijn eigen codeerstijl. Maar als het gaat om het werken in een team, zullen we vaak codes moeten delen met de andere teamgenoten. Het is dus essentieel om een consensus hebben over een norm om iedereen op dezelfde pagina te houden. Een goed geschreven documentatie zou de referentie zijn die het team nodig heeft

Maar anders dan documentatie voor eindgebruikers beschrijft deze documentatie meestal technische procedures zoals code-naamgevingsconventie, die laat zien hoe bepaalde pagina's moeten worden samengesteld, en hoe de API werkt, samen met de codevoorbeelden. Vaak moeten we ook de documentatie inline schrijven met de code (bekend als de opmerkingen) om te beschrijven wat de code aan het doen is.

Bovendien, in het geval waar je hebt nieuwe leden doen mee Uw team later, deze documentatie kan een tijdeffectieve manier zijn om ze te trainen, zodat u ze geen 1-op-1-run op de code hoeft te geven.

Vreemd genoeg helpt het ook de Coder

Het grappige aan coderen is dat soms zelfs de ontwikkelaars zelf begrijpen de code niet die ze hebben geschreven. Dit is met name het geval in gevallen waarin de codes maanden of zelfs jaren onaangetast zijn gebleven.

Een plotselinge noodzaak om de codes om de een of andere reden opnieuw te bezoeken, zou je afvragen wat er in hun hoofd omging toen ze deze codes schreven. Wees niet verbaasd: ik ben eerder in deze situatie geweest. Dit is precies toen ik wenste Ik had mijn code correct gedocumenteerd.

Door uw codes te documenteren, kunt u snel en zonder frustratie de bodem van uw codes doorzoeken, waardoor u veel tijd bespaart die u kunt besteden aan het verkrijgen van de wijzigingen in.

Wat zorgt voor goede documentatie?

Er zijn verschillende factoren om een ​​goed stuk documentatie te bouwen.

1. Veronderstel nooit

Ga er niet vanuit dat uw gebruikers weten wat u weet net zo goed als wat ze wil weten. Het is altijd beter om vanaf het allereerste begin te beginnen ongeacht het vaardigheidsniveau van de gebruiker.

Als u bijvoorbeeld een jQuery-plug-in hebt gebouwd, kunt u zich laten inspireren door de documentatie van SlickJS. Het laat zien hoe de HTML gestructureerd moet worden, waar de CSS en het JavaScript geplaatst moeten worden, hoe de jQuery-plug-in op het meest basale niveau moet worden geïnitialiseerd en zelfs de volledige definitieve opmaak zichtbaar is na het toevoegen van al deze dingen, wat voor de hand ligt.

De bottom line is dat de documentatie is geschreven met het denkproces van een gebruiker, niet van een ontwikkelaar. Door je eigen documentatie op deze manier te benaderen, krijg je een beter perspectief bij het organiseren van je eigen stuk.

2. Volg de standaard

Bij het toevoegen van documentatie die in lijn is met de code, gebruik de standaard verwacht van de taal. Het is altijd een goed idee om elke functie, de variabelen, en de waarde die door de functie wordt geretourneerd te beschrijven. Hier is een voorbeeld van goede inline documentatie voor PHP.

 / ** * Voegt aangepaste klassen toe aan de reeks hoofdtekstklassen. * * @param array $ classes Klassen voor het body-element. * @return array * / function body_classes ($ classes) // Voegt een klasse van groepsblog toe aan blogs met meer dan 1 gepubliceerde auteur. if (is_multi_author ()) $ classes [] = 'group-blog';  retourneer $ klassen;  add_filter ('body_class', 'body_classes'); 

Hierna volgen enkele verwijzingen voor het indelen van inline documentatie met best practices in PHP, JavaScript en CSS:

• PHP: PHP Documentation Standard voor WordPress
• JavaScript: Gebruik JSDoc
• CSS: CSSDoc

Als u SublimeText gebruikt, zou ik voorstellen om DocBlockr te installeren waarmee u slim uw code kunt invullen met inline documentatie.

3. Grafische elementen

Gebruik grafische elementen, ze spreken beter dan tekst. Deze media zijn handig, vooral als je software met grafische interface bouwt. U kunt aanwijselementen toevoegen zoals pijlen, cirkel of alles dat gebruikers kan helpen uit te vinden waar ze heen moeten om de stappen te volbrengen, zonder giswerk.

Het volgende is een voorbeeld uit de Tower-app waar je inspiratie uit kunt putten. Ze leggen efficiënt uit hoe versiebeheer op een aangename manier werkt, waardoor het begrijpelijker is dan het gebruik van opdrachtregels in platte tekst.

4. Doorsnijden

U kunt overwegen een paar dingen in de documentatie in opsommingstabellen en -tabellen te verpakken, omdat dit maakt dat langere inhoud gemakkelijker te scannen en te lezen is voor gebruikers.

Voeg een inhoudsopgave toe en deel de documentatie in gemakkelijk verteerbare secties, maar houd elke sectie relevant voor wat erna komt. Houd het kort en duidelijk. Hieronder is een voorbeeld van mooi georganiseerde documentatie op Facebook. De inhoudsopgave brengt ons waar we naartoe willen in een klik.

5. Herziening en update

Lees ten slotte de documentatie voor fouten en pas deze indien nodig aan of en wanneer er belangrijke wijzigingen zijn aan het product, de software of de bibliotheek. Uw documentatie zou voor iedereen nutteloos zijn als deze niet regelmatig wordt bijgewerkt naast uw product.