Het doel van goede documentatie

Vraag direct een offerte aan →

Technische documentatie maken in 10 stappen

Het schrijven van kwalitatief goede technische documentatie is een vak apart! Documentalisten, technisch schrijvers, handleidingontwerpers en dergelijke moeten beschikken over een waslijst van vaardigheden en eigenschappen, zoals analytisch denkvermogen, kwaliteitsdrang, nieuwsgierigheid, oog voor detail, sociale vaardigheden ten behoeve van communicatie tussen experts en leken, et cetera. Bij Manualise zijn mensen aanwezig met deze vaardigheden. Bij het schrijven en maken van een goede instructie, gebruiksaanwijzing of handleiding verdienen onderstaande stappen extra aandacht. Een aantal stappen komt bij het schrijven van iedere handleiding vrijwel altijd terug.

Belangrijke stappen

1.  Productinformatie verzamelen

Voor het schrijven van technische documentatie moet de juiste informatie kunnen worden opgezocht, georganiseerd, gelabeld en gestructureerd. Het is daarbij doorgaans noodzakelijk om meerdere experts te raadplegen, zoals experts op het gebied van elektronica, installatietechniek, mechanica, gebruikersomgevingen, wetgeving en aansprakelijkheid, enzovoort.

2.  Documentatie schrijven

De manier van schrijven, ook wel technische communicatie genoemd, is een van de belangrijkste aspecten bij het opstellen van goede en begrijpelijke technische documentatie. Volgens TCeurope, de overkoepelende Europese organisatie voor technisch schrijvers, is technische communicatie de wetenschap en kunst van ‘het accuraat, op juiste wijze en effectief kunnen overbrengen van feitelijke informatie aan bepaalde doelgroepen voor specifieke doeleinden’. Het is hiervoor van belang dat u de taal waarin u schrijft volledig beheerst. Dit is inclusief spelling, grammatica en zinsopbouw. Het ‘Simplified Technical English (STE), minimalisme en kennis van de doelgroep zijn enkele belangrijke aspecten die u behulpzaam kunnen zijn bij het realiseren van goede technische communicatie.

3.  Illustraties

Wellicht is het een cliché, maar plaatjes zijn in staat meer te zeggen dan 1000 woorden. Het feit dat 1,1 miljoen Nederlanders niet goed blijkt te kunnen lezen, duidt de waarde van goede illustraties nog eens extra aan. Maar bovenal kan met behulp van een informatieve afbeelding op een meer effectieve manier worden uitgelegd hoe iets werkt en hoe iets uitgevoerd moet worden. Uit een onderzoek naar informatieoverdracht blijkt dan ook dat met illustraties de tijd om iets te leren aanzienlijk wordt verkort en de aandacht van de gebruiker beter kan worden vastgehouden. Een ander groot voordeel is dat je met illustraties levendigheid en kleur kunt toevoegen aan technische handleidingen. Hieraan kan ook de grafische vormgeving van het document op zich een bijdrage leveren. Verder voorkomen illustraties niet alleen ellenlange verklarende teksten, maar ook vertaalkosten. 

4.  Het vertalen van technische documenten

Wanneer een handleiding min of meer de juiste vorm heeft gekregen, dient deze ook nog vaak vertaald te worden. Hierbij is het belangrijk samen te werken met een vertaalbureau dat bekend is met het vertalen van technische documenten. En het liefst ook nog met uw bedrijfstak. Consequent taalgebruik is van groot belang in een handleiding. Zorg ervoor dat het juiste jargon in alle talen wordt uitgewisseld, mocht het vertaalbureau dit zelf niet initiëren. Is het jargon niet bekend, dan kunt u het vertaalbureau verzoeken om de keuze die zij maken te toetsen middels een klankbord met de doelgroep. Wanneer er sprake is van repeterende vertaalopdrachten, kan het bureau steeds de juiste terminologie uit het vertaalgeheugen halen. Dit wordt binnen de branche ook wel ‘terminologiemanagement’ genoemd.

5.  Tools gebruiken

Er bestaan diverse tools voor het effectief maken, beheren en publiceren van technische handleidingen. De meeste tools hebben als uitgangspunt ‘het effectief kunnen samenstellen van documentatie en het stimuleren van hergebruik van content’. Standaarden die hierbij van belang zijn, zijn DITA en XML. Bruikbare softwarepakketten voor het maken, beheren en publiceren van technische handleidingen zijn bijvoorbeeld FrameMaker, MadCap Flare en Adobe InDesign.

6.  Doelgroep kennen

Het kennen van uw gebruiker is een van de belangrijkste voorwaarden voor een goede communicatie. Mensen verschillen in leeftijd, opleidingsniveau, eigenschappen, geslacht, enzovoort. Daarom moeten ze ook op verschillende manieren benaderd worden. Wanneer dit niet op een correcte manier gebeurt, bereikt de informatieoverdracht haar doel niet of in mindere mate. Vraag uzelf dus iedere keer weer af voor wie de handleiding wordt geschreven. Het zich constant bewust zijn van de eigenschappen van de doelgroep is noodzakelijk. Bijvoorbeeld: wordt de (technische) handleiding geschreven voor de consument of voor een installateur? Het doornemen van een handleiding wordt door veel mensen al bestempeld als saai en complex. Voorkom ergernissen door u zich vooraf in de doelgroep te verdiepen.

De inhoud van technische documentatie dient:

• Makkelijk te begrijpen te zijn. Introducties, hoofdstuk- en paragraafkoppen (headings) zorgen ervoor dat de informatie haar weg zal vinden naar de gebruiker. Besteed hier dus extra aandacht aan.
• Kort en ‘to the point’ te zijn. Het is de bedoeling dat het de gebruiker zo min mogelijk inspanning kost om de informatie tot zich te nemen.
• In balans te zijn. Visuele en tekstuele content dienen elkaar te ondersteunen.
• Speciale aandacht te schenken aan storingen. Dit zijn namelijk de gelegenheden waarbij handleidingen het meest geraadpleegd worden.
• Warm, toegankelijk en plezierig te zijn.
• Geleid te worden door het te behalen voordeel: technologie en features van producten moeten worden vertaald naar begrijpelijke en menselijke instructies. De technische handleiding dient voorbeelden en mogelijke scenario’s te bevatten.

7.  Simplified Technical English

Het Simplified Technical English, oftewel STE, is een norm die de afgelopen jaren veel ruimte heeft gewonnen binnen tal van industrieën. Het betreft een ingeperkte taal die woorden en zinsdelen uitsluit die te moeilijk zijn voor de doelgroep of die verwarring kunnen veroorzaken. Het STE staat voor eenduidigheid. Deze vorm van de Engelse taal vindt zijn oorsprong in de vliegtuigindustrie, waar de behoefte ontstond aan een taal die voor iedereen begrijpelijk is en waarbij ambiguïteit (dubbelzinnigheid) wordt uitgesloten. Dit wordt gerealiseerd door simpelweg woorden die meerdere betekenissen kunnen hebben te elimineren. ‘Turn off engines not required’ is een goed voorbeeld van een zin die op verschillende manieren kan worden geïnterpreteerd. Namelijk als ‘turn off the engines that are not required’ of als ‘turning off the engines is not required at all’. Het STE is hierbij van groot belang, omdat het verkeerd interpreteren van een dergelijke zin grote gevolgen kan hebben.

Het STE biedt een aantal basisregels voor het schrijven van documentatie zoals technische handleidingen. Bijvoorbeeld:

• Kies slechts één betekenis indien er meerdere synoniemen voor een woord bestaan en gebruik deze dan consistent. Wijk dus niet meer van af van die keuze voor dat ene woord. Bijvoorbeeld: ‘begin’, ‘start’, ‘commence’, ‘originate’ en ‘initiate’ kunnen in het Engels allemaal ‘beginnen’ betekenen. Het STE heeft voor ‘start’ gekozen, omdat dit werkwoord de meest regelmatige vervoegingen heeft.
• Kies slechts één betekenis indien een woord meerdere betekenissen kan hebben. Zo wordt in het STE het Engelse ‘fall’ louter gebruikt wanneer gedoeld wordt op iets dat door zwaartekracht naar beneden wordt gehaald. Dit woord wordt dus bijvoorbeeld niet gebruikt in de betekenis van ‘ten onder gaan’. Deze eenduidigheid voorkomt verwarring en eventuele grotere gevolgen.
• In het Engels hebben bepaalde woorden verschillende grammaticale functies. Zo zijn er woorden die als zelfstandig naamwoord en als werkwoord kunnen dienen. Neem als voorbeeld het woord ‘switch’. Het kan de fysieke schakelaar betreffen, maar ook het ‘schakelen’ zelf als een werkwoord. Het STE heeft er in dergelijke gevallen voor gekozen het alleen te gebruiken als zelfstandig naamwoord. Voor het werkwoord wordt ‘turn off’ of ‘turn on’ gebruikt.

8.  Minimalisme

De minimalistische benadering vindt zijn oorsprong in 1982. De grondelgger van het minimalisme is John Carroll. In Nederland is dr. Hans van der Meij van de Universiteit Twente actief bezig met het minimalisme. Middels observaties hebben Caroll en zijn collegae achterhaald op welke manieren gebruiksondersteuning effectiever aansluit op het handelen van de gebruiker, omdat zij simpelweg niet tevreden waren over de bestaande vormen van gebruiksondersteuning (zoals technische handleidingen). Het minimalisme wordt bestempeld als een ontwerpfilosofie. De vier basisprincipes van het minimalisme zijn:

• Wees niet te beschrijvend en kies voor een benadering die gericht is op actie. Gebruikers willen dingen doen in plaats van lezen! De centrale rol van de gebruiker wordt hiermee nog eens extra benadrukt.
• Leg het hulpmiddel vast in het takendomein. Een tool is een middel om een doel te bereiken. Dit principe zorgt ervoor dat de gebruiker zelf de taken selecteert die van betekenis zijn.
• Vergissen is menselijk. Ondersteun om deze reden foutenherkenning en herstel. Bij het omgaan met vergissingen zijn er verschillende manieren om de bekwaamheid en comfortniveaus van de gebruiker te vergroten.
• Ondersteun de gebruiker in het doen, studeren en lokaliseren. Volgens het minimalisme dient een aanwijzing zoveel mogelijk aan te sluiten op de uiteenlopende behoeften en neigingen van de doelgroep. Ook dit principe sluit aan op de centrale rol die de gebruiker heeft volgens het minimalisme.

9.  Inhoud

Omdat de inhoud van alle technische documentatie en handleidingen met name door het product zelf bepaald wordt, is deze vanzelfsprekend voor ieder product anders. Echter, het doel van de documentatie is wel vrijwel altijd hetzelfde. Namelijk de gebruiker instructies geven over hoe het product veilig en op een goede manier gebruikt kan worden.

De NEN 5509 verschaft een minimum aan normen voor de informatieve inhoud, formulering, structuur en presentatie van handleidingen. Een goede technische handleiding dient volgens deze norm ten minste de volgende inhoud te bevatten:

• Technische specificaties.
• Voorzorgsmaatregelen en veiligheidsinstructies.
• Montage, installatie, ingebruikname.
• Beschrijving van het product; samenstelling van het product.
• Beschrijving van de bediening, wijze van gebruik.
• Buitenbedrijfstelling.
• Onderhoud en onderhoudsschema.
• Demontage, sloop, opslag en transport.
• Storingen en reparatie.
• Afdanken.
• Milieu.

10.  Output genereren

Gebruikers willen over productinformatie beschikken op het moment dat zij deze nodig hebben en wel direct. Ondanks nog steeds verplicht voor CE-markering om te voldoen aan de Europese richtlijnen, voldoet een papieren handleiding alleen niet aan deze behoefte. Om deze reden hebben ontwikkelaars van single source software, zoals MadCap Software, het mogelijk gemaakt om naast print output (zoals PDF) vanuit dezelfde content met vrijwel hetzelfde gemak ook online output (HTML5, WebHelp App, EPUB, DITA etc.) te genereren. Dezelfde informatie is op die manier ook via desktop, tablet of smartphone te raadplegen.

Werkwijze om documentatie te maken

Welke vorm de documentatie ook heeft, bij het maken ervan doorlopen wij altijd de volgende fases: