Wat zijn goede voorbeelden van technische documentatie?

Dit artikel laat aan de hand van voorbeelden zien waar je op moet letten bij het maken van professionele technische documentatie voor machines, installaties, apparaten, productieprocessen, software enzovoort.

Allereerst is het belangrijk je te realiseren dat technische documentatie een breed begrip is. Technische datasheets, installatiehandleidingen, onderhoudsinstructies, werkinstructies, procesbeschrijvingen, veiligheidssheets, onderdelenlijsten en technische tekeningen kunnen bijvoorbeeld allemaal onder de noemer technische documentatie vallen.

Overigens: in veel Europese regelgeving wordt met technische documentatie ook wel het technisch dossier bedoeld, dat ook bijvoorbeeld testrapporten, de risicoanalyse en conformiteitsverklaring bevat. Dit verstaan wij in dit artikel niet onder technische documentatie. Lees daarvoor het artikel "Wat moet er in het Technisch Dossier". 

Laten we naar wat voorbeelden kijken.

Voorbeelden van technische documentatie

Technische documentatie heeft meestal een titelpagina. Gebruiksaanwijzingen voor machines, apparaten en andere CE-producten moeten aan wettelijke eisen voldoen. Dit kunnen eisen zijn uit een richtlijn of verordening, maar ook uit een norm. 

Het volgende voorbeeld laat zien dat op de titelpagina het type technische documentatie is benoemd, namelijk 'Installatie- en gebruikersinstructies'. Dit wordt onder andere door de EN 82079-1 voorgeschreven. 

In de marge zie je de tekst 'These are the original English instructions': dit is een eis vanuit de Machinerichtlijn. De vertaling moet de tekst 'Dit is een vertaling van de originele Engelse handleiding' bevatten.

Ook de vermelding van de productnaam is een eis die wordt gesteld in de meeste richtlijnen. Indien de machine nog een bepaald type of model zou hebben, moet ook dat vermeld worden.

Verder zie je het volgende op het titelblad dat ook uit de EN-82079-norm volgt:

• Vermelding datum en versienummer
• Een afbeelding waardoor de gebruiker visueel kan herkennen op welke machine de documentatie betrekking heeft

Het is in principe niet verplicht om het CE-logo af te beelden. Deze verplichting geldt alleen voor op de machine of het apparaat en eventueel de verpakking. Voor een eenduidige communicatie kiezen wij er vaak voor dit wel te doen.

Welke elementen zie je in de volgende afbeelding terugkomen?

Het volgende voorbeeld is geen machine, maar een elektrisch apparaat. De eis om aan te duiden of het een vertaling of een originele versie betreft, geldt alleen voor machines.

Het design van de technische documentatie die wij ontwikkelen, maken we met behulp van Adobe Illustrator en InDesign.

Het voorbeeld hierna laat een standaard inhoudsopgave zien voor een handleiding. Deze bevat alle gangbare secties. Vaak nemen we een dergelijke inhoudsopgave als vertrekpunt en passen die aan voor het product waarvoor we de technische documentatie schrijven.

Dit voorbeeld laat een uitgebreide inhoudsopgave zien voor een machine, gemaakt op basis van het voorgaande voorbeeld.

Bij  software spreken we ook van technische documentatie. De inhoudsopgave van de online help of de softwaredocumentatie heeft de vorm van een menu.

Een ander belangrijk onderdeel in goede technische documentatie is een beschrijving van het beoogde gebruik. Het volgende voorbeeld laat zien hoe bij deze machine het beoogde gebruik en onbedoelde gebruik worden beschreven.

En nog een voorbeeld voor het bedoelde en onbedoelde gebruik:

Technische specificaties zijn vaak een integraal onderdeel van gebruikershandleidingen.

Maar deze kunnen ook in een losse datasheet worden ondergebracht:

Goede documentatie wordt rondom topics geschreven. 

In technische communicatie is topic-based schrijven een modulaire benadering van contentcreatie, waarbij de content is gestructureerd rond onderwerpen (topics) die kunnen worden gemengd en hergebruikt in verschillende contexten. Een topic heeft een duidelijk begin en einde.

Topic-based schrijven is zeer geschikt voor technische documentatie. Tools die deze benadering ondersteunen, slaan content doorgaans op in XHTML- of andere XML-indelingen en ondersteunen hergebruik, beheer en dynamische samenstelling van gepersonaliseerde informatie.

Doorgaans kunnen topics worden geordend in de inhoudsopgave, zodat de gebruiker eenvoudig naar de relevante topic kan navigeren die een oplossing biedt voor het probleem.

In goede documentatie bestaat een topic vaak uit verschillende informatietypen. Zo zijn er de volgende informatietypen:

• Veiligheidswaarschuwingen
• Conceptuele informatie
• instructies of procedures
• Tabellen
• Illustraties

Voorbeeld van verschillende informatietypen in technische documentatie: een veiligheidsinstructie, conceptuele informatie en een procedure.

Ook het volgende voorbeeld uit een AEG-handleiding laat verschillende informatietypen zien
.

De informatietypen 'procedure' en 'illustratie'

Met behulp van Simplified Technical English (STE) kunnen heldere teksten worden geschreven. Heldere teksten zijn de basis voor begrijpelijke documentatie en dienen ter verbetering van de technische communicatie.

STE zorgt ervoor dat de technische documentatie beter te begrijpen is door ondubbelzinnig  en consequent taalgebruik.

De ASD-STE100 is de standaard waarin het STE is vastgelegd. De standaard bestaat uit twee delen: een set schrijfregels en een woordenboek.

De 53 schrijfregels hebben als gemeenschappelijke deler  dat te allen tijde alleen de kern van de informatie wordt beschreven. Deze informatie moet in heldere en begrijpelijke taal worden gepresenteerd. Hiervoor dient het woordenboek.

Het woordenboek bestaat uit een lijst van zo’n 850 woorden die zijn toegestaan. Elk woord mag slechts als één toegestane woordklasse worden gebruikt. Zo specificeert het woordenboek het woord 'oil' bijvoorbeeld als zelfstandig naamwoord. Daarom mag 'oil' niet worden gebruikt als werkwoord.

Toegestaan gebruik van het woord 'illuminate' als werkwoord

Toegestaan gebruik van het woord 'oil' als werkwoord

Het STE-Woordenboek is online beschikbaar gemaakt via onze gratis STE-Tool.

Een ander veelgebruikt uitgangspunt voor het schrijven van heldere documentatie zijn de ‘Principles of Minimalism’. Minimalisme is een op actie gerichte benadering met als uitgangspunt dat gebruikers zo snel mogelijk dingen gedaan willen hebben.

Een van de vier principes van het minimalisme is dat er on-the-spot problem-solving informatie wordt gegeven. Dat is goed zichtbaar in het volgende voorbeeld (laatste paragraaf / informatie type).

Goede technische documentatie beschrijft de risico's, die met het gebruik van een product te maken hebben, op een eenduidige manier en volgens een systeem van gevaarniveau.Een risicobeoordeling staat vaak aan de basis hiervan. 

Er worden verschillende niveaus van gevaren onderscheiden, namelijk: GEVAAR (DANGER), WAARSCHUWING (WARNING), VOORZICHTIG (CAUTION) en LET OP (NOTICE).

De betekenis van deze signaalwoorden staat in het volgende voorbeeld.

Illustraties verrijken en verduidelijken technische documentatie. Soms kunnen ze op zichzelf staan, maar de vuistregel is dat ze een tekstuele instructie moeten verduidelijken.

Voorbeeld van een illustratie uit de technische documentatie van de Speedcomfort

Voorbeeld van illustraties uit de technische documentatie van de AEG-kokendwaterkraan

Voorbeeld van illustraties uit de handleiding van een Gazelle elektrische bakfiets

Ook de vormgeving en het medium zijn belangrijk voor de documentatie. Het volgende voorbeeld is een pagina uit de handleiding van een elektrische tandenborstel. Je zit hier een consistente doorvoering van huisstijlelementen in zowel de  lay-out als in de stijl van de illustraties.

Gebruikers raadplegen documentatie het liefst via verschillende kanalen. Of eigenlijk: een gebruiker denkt niet in kanalen, maar wil over informatie kunnen beschikken op het moment dat  deze nodig is, ongeacht het kanaal. 

Voor het maken, beheren en publiceren naar verschillende outputvormen (print en elektronisch) van technische documentatie kan een contentmanagementsysteem (CMS) worden gebruikt. Voorbeelden van dergelijke systemen zijn MadCap Flare, Paligio, Author-it, Adobe Framemaker en Fischer.

 

Dezelfde content via diverse outputformaten beschikbaar

Voorbeeld van printoutput. 

Voorbeeld van online (HTML) output 

Neem contact met ons op voor het maken van uw technische documentatie.

NEEM CONTACT OP