Close

Betere documentatie samenstellen

Je bent net begonnen met een project en nu moet je documentatie te leveren (hint: $#*&^!%).

Ontmoedigend? Zo lijkt het wel, maar we helpen je graag! Hieronder vind je documentatie over documentatie [(knipoog)] - een stapsgewijze handleiding met professionele tips om je door het proces te loodsen. Laten we aan de slag gaan!


Dus waarom zou het me iets schelen?

Documentatie helpt, simpel gezegd, mensen te doen wat ze moeten doen. Maar zoals bij de meest onverklaarbare buitengewone dingen, doet het veel meer dan alleen maar mensen helpen om hun ding te doen. Documentatie helpt gebruikers en teams met:

Mentale energie besparen

Doe je werk zonder al te hard na te denken en met zo min mogelijk moeite.

Voor consistentie zorgen

Zorg dat je lezers dezelfde informatie, processen en plannen op een consistente manier gebruiken.

Werkdruk verminderen

Introduceer teamgenoten snel en efficiënt, zodat ze meteen aan het werk kunnen.

Branding verbeteren

Maak een verklaring over hoe je je externe klanten en interne werknemers behandelt door ondersteunend en behulpzaam te zijn.

Als je geen waarde biedt, laat niemand zijn oog op je vallen. Het is aan jou om de manier waarop je lezers denken over de informatie die je aanbiedt vorm te geven – en ze te informeren over het belang ervan.

Wat is documentatie?

Documentatie is alles wat je denkt dat het is: een set documenten. Een kompas voor je gemiddelde eindgebruiker. Een draaiboek voor de software-engineer in je. Technischer bezien is documentatie meestal tekst of illustraties die bij software horen. Deze documenten fungeren als een naslaggids waarin wordt uitgelegd hoe die software werkt, wat die doet en hoe die moet worden gebruikt. Softwareteams kunnen documentatie naslaan voor productvereisten, releasenotes of ontwerpspecificaties. Technische teams kunnen documenten gebruiken om code, API's te beschrijven en hun softwareontwikkelingsprocessen vast te leggen. Extern heeft documentatie vaak de vorm van handleidingen en gebruikershandleidingen voor systeembeheerders, ondersteuningsteams en andere eindgebruikers.

Alle documentatie moet erop gericht zijn om 2 hoofdzaken te bereiken:

1. Gebruikers informeren

2. Gebruikers in staat stellen iets te bereiken

Begin je documentatie met het definiëren van het onderwerp, het doel of de doelstelling. Dit helpt je doelgroep meteen te begrijpen waarover je tekst gaat.

Soorten documentatie

Zoals we eerder al hebben gezegd, is documentatie er in alle soorten en maten, intern en extern. Elk soort document verschilt in toon, vorm, bijdragers, doelgroep en inhoud. De meest voorkomende soorten zijn:



Interne documentatie
teamdocumentatie-illustratie

Teamdocumentatie

Teamdocumentatie helpt bij het belichten van het werk dat wordt gedaan, zodat teams, nou ja, als team kunnen werken. Deze documenten kunnen projectplannen, teamroosters, statusrapporten, notulen en al die andere dingen zijn die een team nodig heeft om functioneel en efficiënt te werken. Dit type documentatie is gedetailleerd, zodat alle neuzen in dezelfde richting blijven staan.

naslagdocumentatie-illustratie

Naslagdocumentatie

Naslagdocumentatie informeert het bedrijf over belangrijke onderwerpen, processen en beleidslijnen. Dit kunnen beleidsregels zijn die door de HR-afdeling zijn opgesteld, juridische processen voor het inhuren van externe leveranciers of uitlegartikelen over het regelen van secundaire arbeidsvoorwaarden. Naslagdocumentatie wordt geschreven door een kleine groep mensen voor een groot en gevarieerd publiek. Begrijpelijke inhoud is dus erg belangrijk.

projectdocumentatie-illustratie

Projectdocumentatie

Projectdocumentatie is van zichzelf gericht op specifieke projecten en biedt de broodnodige structuur voor productontwikkeling. Het omvat voorstellen, documenten met productvereisten, ontwerprichtlijnen of schetsen, roadmaps en andere relevante informatie die nodig is voor ontwikkeling –met bijdragen van projectmanagers, ingenieurs, ontwerpers en meer.



EXTERNE DOCUMENTATIE
systeemdocumentatie-illustratie

Systeemdocumentatie

Systeemdocumentatie beschrijft code, API's en andere processen die ontwikkelaars en programmeurs vertellen welke soorten methoden en functies kunnen worden gebruikt bij het ontwikkelen van specifieke software, evenals beperkingen en vereisten. In dit type documentatie staan codefragmenten, zoals voorbeelden van API-aanroepen en -reacties, centraal.

illustratie-documentatie-eindgebruikers

Documentatie voor eindgebruikers

Gebruikersdocumentatie is vaak het meest zichtbare type documentatie. Het moet gemakkelijk te lezen en te begrijpen zijn, en worden bijgewerkt voor elke nieuwe softwareversie. Het bestaat uit 'Lees mij'-documenten, installatiehandleidingen, handleidingen voor beheerders, productkennisbanken en tutorials (de meest nuttige van alles).En net als naslagdocumentatie wordt het geschreven door een kleine groep mensen voor een grote groep lezers. Begrijpelijke inhoud is dus erg belangrijk.

Het opnemen van voorbeelden in je documentatie biedt je doelgroep veel meerwaarde. Ze dienen als brug om concepten en ideeën te begrijpen en garanderen de lezer dat je weet waar je het over hebt.

Documentatie aanmaken

Het uiteindelijke doel is ervoor te zorgen dat je documentatie nuttig is voor de lezer. We bieden je hieronder als tutorial vormgegeven documentatie voor je documentatie (hoe meta ...), hieronder zodat de klus net wat makkelijker wordt.

1. Onderzoek

Wat moeten gebruikers weten over je product, project of API? Gebruik je analyseprogramma om te zien wat er wordt gezocht, blader door online communityforums en discussiegroepen en doe gebruikersonderzoek en bruikbaarheidstests. Zorg ervoor dat je je product kent en weet hoe je gemakkelijk gebruikersvragen, nieuwe functies en workflows kunt uitleggen.

2. Begin gewoon

Geef duidelijk aan waarover je documentatie gaat en waarom het waardevol is voor de lezer om de documentatie te lezen.

3. Leg de details vast

Maak een overzicht en schrijf. Gebruik een passende toon (wees menselijk!) voor je doelgroep. Wees ook consistent en beknopt. Communiceer belangrijke details duidelijk.

4. Maak alles op

Structureer je pagina zodat deze gemakkelijk van begin tot eind kan worden gevolgd. Haal overbodigheden eruit en splits lange inhoud op met visuals zoals diagrammen, screenshots en afbeeldingen.

5. Controleer

Verzamel feedback over de taalkundige aspecten van je tekst. Zorg ervoor dat reviewers het doel van je documentatie begrijpen. Dit zal helpen om verwarrende taal te ontwarren of ontbrekende stappen in kaart te brengen.

6. Publiceer

Na revisies en bewerkingen ben je klaar voor publicatie! Publiceer je werk en leg je oor te luisteren voor eventuele feedback en opmerkingen. Documenteren is niet iets dat je een keertje doet en dat was het dan!

Gouden grepen

Zoals je kunt zien, is documentatie meer dan alleen het samenstellen van een heleboel instructies en woorden. Maar er is een methode die je houvast biedt. Onthoud deze leidende principes voor- en achteraf, in je slaap en nadat je je documentatie hebt samengesteld:

Houd het kort

Je documentatie moet precies de juiste hoeveelheid informatie bevatten om de klus te klaren, zónder dat er een helpticket moet worden ingediend. Vermeld de belangrijkste punten en bied lezers de mogelijkheid om in te zoomen op details.

Visuals zijn belangrijk

Visuals zijn de sleutel tot begrip. Productontwerp, codevoorbeelden, productdemo's, screenshots en videozelfstudies helpen je lezer om het concept, de uitleg of de taken volledig te begrijpen. Houd ook rekening met de lay-out, leesbaarheid en begrijpelijke stukken tekst.

Ken je doelgroep

Verplaats je in de gebruiker. Ken je lezer en doorloop zijn gebruikersreis van je product en je documentatie. Dit moet altijd de leidraad zijn voor hoe en wat je schrijft.

Ga direct aan de slag

De beste documentatie is duidelijk, beknopt, informatief en vooral van toegevoegde waarde voor de doelgroep. Ontdek software voor teamsamenwerking, zoals Confluence voor je documentatie – en besteed minder tijd aan het opzoeken van dingen en meer tijd aan de uitvoering.

Meer informatie