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 ontwikkelingsucces 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 door iedereen worden verteerd. Technisch gezien moeten we een machinetaal (code) vertalen in een taal die begrijpelijk is voor mensen, 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 om te begrijpen hoe een code werkt, uiteraard. 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 "how-to". De vuistregel bij het maken van documentatie voor algemene gebruikers is dat deze duidelijk moet 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 '"First Steps With 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 consensus te hebben over een standaard om iedereen op dezelfde pagina te houden. Een goed geschreven documentatie zou de referentie zijn die het team nodig heeft

In tegenstelling tot de documentatie voor de eindgebruiker beschrijft deze documentatie meestal technische procedures zoals conventies voor het benoemen van codes, het laten zien hoe bepaalde pagina's moeten worden samengesteld en hoe de API samenwerkt 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.

Als u later nieuwe leden heeft die lid worden van uw team, kan deze documentatie bovendien een tijdeffectieve manier zijn om hen 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 de code die ze hebben geschreven niet begrijpen . 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 bekijken, 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 wanneer ik zou willen dat ik mijn code correct had 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 binnenhalen van de wijzigingen.

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 en wat ze willen 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 geïnitialiseerd moet worden en zelfs de volledige definitieve opmaak getoond wordt 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

Voeg bij het toevoegen van documentatie die in overeenstemming is met de code de standaard verwacht van de taal toe . 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.

 / ** * Hiermee voegt u 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 : UseJSDoc
• 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 aanwijzingselementen zoals pijlen, een cirkel of iets toevoegen waardoor gebruikers kunnen achterhalen waar ze naartoe moeten gaan 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 prettige manier werkt, waardoor het begrijpelijker is dan het gebruik van opdrachtregels in platte tekst.

4. Doorsnijden

U kunt overwegen om 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 met wat daarna 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 aan waar nodig 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.

Hoe Wikipedia-pagina's omzetten in e-boeken

Als je net als ik bent, dan hou je waarschijnlijk wel van Wikipedia, de favoriete internetencyclopedie van iedereen. Het bevat een enorme database met inhoud over bijna elk onderwerp onder de zon en in verschillende talen. Als je je op een reis voorbereidt, zou je waarschijnlijk wat van dit leesmateriaal bewaren om later, offline, te lezen, maar wat als je er een e-boek van zou kunnen maken

(Technische en ontwerptips)

Uw pc in- en uitschakelen met Android-telefoon

Veel mensen hebben de gewoonte om hun pc altijd te laten werken en gaan in veel gevallen naar buiten zonder deze te sluiten. Nou, het goede nieuws voor zulke mensen is dat ze hun Android-telefoon kunnen instellen om te werken als een afstandsbediening voor hun pc . Dus wanneer u uw pc laat draaien, kunt u hem eenvoudig uitschakelen, in de sluimerstand zetten of hem op afstand starten met uw smartphone

(Technische en ontwerptips)