U zoekt op: {{ keyword }}

Wat zijn goede voorbeelden van technische documentatie?

INSTRKTIV Blog - Tools & efficiency

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, risicoanalyses en conformiteitsverklaringen bevat. Dit verstaan wij in dit artikel niet onder technische documentatie.

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. 

titelblad

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?

cover technische documentatie

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.

machine documentatie

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.

inhoudsopgave technische documentatie

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

menu software documentatie

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.

beoogde gebruik

En nog een voorbeeld voor het bedoelde en onbedoelde gebruik:

redelijkerwijs te voorzien misbruik

Technische specificaties zijn vaak een integraal onderdeel van gebruikershandleidingen.

technische specificaties

Maar deze kunnen ook in een losse datasheet worden ondergebracht:

voorbeeld technische documentatie

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

informatietypen

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

heldere instructies

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

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.

simplified technical english

Toegestaan gebruik van het woord 'illuminate' als werkwoord

STE

Toegestaan gebruik van het woord 'oil' als werkwoord

ste tool

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).

minimalisme

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.

veiligheidsinstructies

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

illustraties

Voorbeeld van een illustratie uit de technische documentatie van de Speedcomfort

technische illustraties

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

illustraties

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.

layout

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.

 online documentatie

Dezelfde content via diverse outputformaten beschikbaar

print documentatie

Voorbeeld van printoutput. 

technische documentatie voorbeeld

Voorbeeld van online (HTML) output 

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

NEEM CONTACT OP

 

ferry vermeulen

Ferry Vermeulen

Oprichter van INSTRKTIV en wil gebruikers helpen om expert te worden in het gebruik van een product en zo bij dragen aan een positieve UX. Ferry wil organisaties helpen om hun productaansprakelijkheid te verminderen. Groot liefhebber van koken, reizen en (vooral elektronische) muziek. Ook te vinden op:
ProfielpaginaLinkedin en Twitter!


Dit is misschien ook interessant voor jou

  • 01 juli 2021

    Learn How the New Market Surveillance Regulation Affects Non-EU Businesses And What You Should Do To Keep Selling Products On The European Market (and UK)

    In this webinar we will outline what the effects for non-EU businesses selling products on the European market are when the new Market Surveillance Regulation comes into force. ...

    LEES VERDER

  • 30 juni 2021

    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, software etc....

    LEES VERDER