Sie sind auf Seite 1von 68

Dezember 2011

ICS 01.110 VDI-RICHTLINIEN December 2011

VEREIN Technische Dokumentation VDI 4500


DEUTSCHER Dokumentationsprozess
INGENIEURE Planen, Gestalten, Erstellen Blatt 4 / Part 4
Technical documentation
Documentation process
Former edition: 12/09 Draft, in German only
Frühere Ausgabe: 12.09 Entwurf, deutsch

Ausg. deutsch/englisch
Planning, layout, creation Issue German/English

Die deutsche Version dieser Richtlinie ist verbindlich. No guarantee can be given with respect to the English transla-
tion. The German version of this guideline shall be taken as
authoritative.

Inhalt Seite Contents Page

Vorbemerkung . . . . . . . . . . . . . . . . . . . 2 Preliminary note . . . . . . . . . . . . . . . . . . 3


Einleitung . . . . . . . . . . . . . . . . . . . . . 2 Introduction . . . . . . . . . . . . . . . . . . . . 3
1 Anwendungsbereich . . . . . . . . . . . . . 4 1 Scope . . . . . . . . . . . . . . . . . . . . . 5
1.1 Ihr Nutzen . . . . . . . . . . . . . . . . . 4 1.1 Your benefit . . . . . . . . . . . . . . . . 5
1.2 Was gehört zur 1.2 What constitutes
Technischen Dokumentation? . . . . . . . 6 technical documentation? . . . . . . . . . 7
2 Vom Produktlebenszyklus zum 2 From the product lifecycle up to
Dokumentationsprozess . . . . . . . . . . . 8 documentation process . . . . . . . . . . . 9
3 Dokumentation planen . . . . . . . . . . . . 12 3 Planning of documentation . . . . . . . . . 13
3.1 Dokumentenarten. . . . . . . . . . . . . . 12 3.1 Document types . . . . . . . . . . . . . . 13
3.2 Planungsschritte . . . . . . . . . . . . . . 12 3.2 Planning steps . . . . . . . . . . . . . . . 13
3.3 Daten aufbereiten. . . . . . . . . . . . . . 24 3.3 Preparation of data . . . . . . . . . . . . . 25
4 Dokumentation gestalten . . . . . . . . . . 26 4 Layout of documentation . . . . . . . . . . 27
4.1 Grundsätze . . . . . . . . . . . . . . . . . 28 4.1 Basic principles . . . . . . . . . . . . . . 29
4.2 Layout, Farbe, Text und Bild . . . . . . . . 28 4.2 Layout, Colour, Text and Image . . . . . . 29
4.3 Ausgabemedium . . . . . . . . . . . . . . 30 4.3 Output medium . . . . . . . . . . . . . . 31
5 Dokumentation erstellen . . . . . . . . . . . 30 5 Creation of documentation . . . . . . . . . 31
5.1 Strukturieren . . . . . . . . . . . . . . . . 30 5.1 Structuring . . . . . . . . . . . . . . . . . 31
5.2 Modularisieren . . . . . . . . . . . . . . . 34 5.2 Modularising . . . . . . . . . . . . . . . . 35
5.3 Standardisieren . . . . . . . . . . . . . . . 36 5.3 Standardisation. . . . . . . . . . . . . . . 37
5.4 Erstellen . . . . . . . . . . . . . . . . . . 38 5.4 Creation . . . . . . . . . . . . . . . . . . 39
5.5 Endfassung . . . . . . . . . . . . . . . . . 42 5.5 Final version . . . . . . . . . . . . . . . . 43
5.6 Dokumentation anpassen. . . . . . . . . . 44 5.6 Adapting of documentation . . . . . . . . 45
6 Qualitätsmanagement . . . . . . . . . . . . 46 6 Quality management . . . . . . . . . . . . . 47
6.1 Schwachstellenanalyse . . . . . . . . . . . 48 6.1 Weak point analysis . . . . . . . . . . . . 49
6.2 Prüfungen am Produkt . . . . . . . . . . . 54 6.2 Acceptance tests with the product itself . . 55
6.3 Akzeptanzuntersuchungen . . . . . . . . . 54 6.3 Acceptance tests . . . . . . . . . . . . . . 55
6.4 Anforderungen an den Technischen 6.4 Requirements that the technical writer
Redakteur. . . . . . . . . . . . . . . . . . 56 must meet . . . . . . . . . . . . . . . . . 57
Glossar . . . . . . . . . . . . . . . . . . . . . . 60 Glossary . . . . . . . . . . . . . . . . . . . . . . 61
Schrifttum . . . . . . . . . . . . . . . . . . . . . 67 Bibliography . . . . . . . . . . . . . . . . . . . . 67

VDI-Gesellschaft Produkt- und Prozessgestaltung (GPP)


Fachbereich Technischer Vertrieb und Produktmanagement

VDI-Handbuch Produktentwicklung und Konstruktion


Vorbemerkung

Vorbemerkung
Der Inhalt dieser Richtlinie ist entstanden unter Beachtung der Vorgaben und
Empfehlungen der Richtlinie VDI 1000.

Allen, die ehrenamtlich an der Erarbeitung dieser VDI-Richtlinie mitgewirkt


haben, sei gedankt.
Eine Liste der aktuell verfügbaren Blätter dieser Richtlinienreihe ist im Inter-
net abrufbar unter www.vdi.de/4500.

Einleitung
Die vorliegende Richtlinie VDI 4500 Blatt 4 behandelt Planung, Gestaltung
und Erstellung im Dokumentationsprozess. Die folgende Übersicht zeigt
Blatt 4 im Kontext der Richtlinienreihe VDI 4500.

Blatt Inhalte Zielgruppe

Blatt 1: • Grundlagen der Technischen • Geschäftsleiter hinsichtlich der Verant-


Begriffsdefinitionen Dokumentation wortung und Haftung
und rechtliche • Dokumentationsarten • Führungskräfte hinsichtlich des Einsat-
Grundlagen • rechtliche Forderungen, zes qualifizierten Personals und des
Rechtsnormen Bereitstellens von Ressourcen
• Dokumentationspflichten • ausführende Personen, die mit dem
• Kundenforderungen Erstellen Technischer Dokumentation
• Produktlebenszyklus beauftragt sind
• externe Dienstleister, die eigenverant-
wortlich Aufgaben übernehmen können

Blatt 2: • organisatorische Verant- • Geschäftsleiter hinsichtlich der Verant-


Organisieren und wortung wortung und Haftung
Verwalten • Schnittstellen zwischen • Führungskräfte hinsichtlich des Einsat-
Verantwortungen zes qualifizierten Personals und des
• Projektmanagement Bereitstellens von Ressourcen
• Freigabeprozeduren • ausführende Personen, die mit dem
• Datensicherung und Erstellen Technischer Dokumentation
Archivierung beauftragt sind
• externe Dienstleister, die eigenverant-
wortlich Aufgaben übernehmen können

Blatt 3: • Nutzergruppe und • Führungs- und Fachkräfte von Pro-


Erstellen und Vertei- Anwendungsvorteile duktherstellern und -anwendern für
len von elektroni- • Bestandteile und Realisie- Ersatzteildokumentation
schen Ersatzteil- rung eines elektronischen • externe Dienstleister, die eigenverant-
informationen Ersatzteilkatalogs wortlich Aufgaben übernehmen können
• Schnittstellen
• Datenaustausch, Austausch-
formate
• Praxisbeispiele, Checklisten

Blatt 4: • Ziel- und Benutzergruppen • Führungs- und Fachkräfte, die mit dem
Dokumentations- • Bausteine der Prozesskette Erstellen Technischer Dokumentation
prozess: • Werkzeuge beauftragt sind
– Planen • Qualitätsmanagement • externe Dienstleister, die eigenverant-
– Gestalten wortlich Aufgaben übernehmen können
– Erstellen • Personen, die Informationen für die
Technische Dokumentation liefern

–2– VDI 4500 Blatt 4 / Part 4


Preliminary note

Preliminary note
The content of this guideline has been developed in strict accordance with the
requirements and recommendations of the guideline VDI 1000.
All rights are reserved, including those of reprinting, reproduction (photocop-
ying, micro copying), storage in data processing systems and translation,
either of the full text or of extracts.
The use of this guideline without infringement of copyright is permitted sub-
ject to the licensing conditions specified in the VDI Notices (www.vdi-rich-
tlinien.de).
We wish to express our gratitude to all honorary contributors to this guideline.

A catalogue of all available parts of this series of guidelines can be accessed


on the internet at www.vdi.de/4500.

Introduction
The present guideline VDI 4500 Part 4 deals with planning, layout and crea-
tion in the documentation process. The following overview shows Part 4 in
the context of the series of guidelines VDI 4500.

Part Contents Target group

Part 1: • basic principles of technical • managing directors in respect of respon-


Definitions • documentation sibility and liability
and legal • documentation types • senior managers with respect to the
basics • legal requirements, deployment of qualified personnel and
legal standards the provision of resources
• documentation duties • executives who are assigned the task of
• customer requirements creating technical documentation
• product lifecycle • external service providers, who can dis-
charge duties under their own responsi-
bility

Part 2: • organisational responsibility • managing director in respect of


Organisation and • interfaces between responsi- responsibility and liability
management bilities • senior managers in respect of the deploy-
• project management ment of qualified personnel and provision
• approval procedures of resources
• data protection and archiving • executives who are assigned the task of
creating technical documentation
• external service providers, who can
discharge duties under their own respon-
sibility

Part 3: • user group and advantages of • experts and management of product


Producing and dis- use manufacturers and users for spare parts
tributing electronic • components and implementa- documentation
spare parts infor- tion of an electronic spare • external service providers, who can
mation parts catalogue assume tasks under their own responsi-
• interfaces bility
• data exchange, exchange
formats
• practical examples, checklists

Part 4: • target and user groups • experts and management, who are
Documentation • modules of the process chain entrusted with the task of creating techni-
process: • tools cal documentation
– planning • quality management • external service providers, who can
– layout assume duties under their own responsi-
– creation bility
• persons who deliver information for tech-
nical documentation

VDI 4500 Blatt 4 / Part 4 –3–


Anwendungsbereich
Ihr Nutzen

Blatt Inhalte Zielgruppe

Blatt 5: • betriebswirtschaftliche • Geschäftsleiter hinsichtlich der Bewer-


Dokumentations- Aspekte tung von Dokumentationsleistungen
prozess: • Optimieren von Informations- • kaufmännische Führungskräfte hin-
Wirtschaftlich und Dokumentationsprozes- sichtlich der betriebswirtschaftlichen
dokumentieren sen Bewertung
• projektbezogene Kalkulation • technische Führungskräfte hinsichtlich
• Nutzen interner Ressourcen, des Umsetzbarkeit mit vorhandenen
Einbinden externer Dienst- oder zugekauften Ressourcen
leister • Produktmanager oder Projektleiter hin-
• Praxisbeispiele, Checklisten sichtlich der kostengerechten Integra-
tion in den Produktlebenszyklus
• ausführende Personen, die mit dem
Erstellen und Koordinieren Technischer
Dokumentation beauftragt sind

Blatt 6: • Publizieren als Teil des • Verantwortliche, die für die datentechni-
Dokumentations- Dokumentationsprozesses sche Infrastruktur, die Dokumentation
prozess: Publizieren • rechtliche Aspekte und die Verteilung der Dokumente ver-
• Informationszugriff, Schnitt- antwortlich sind
stellen und Standards • Führungs- und Fachkräfte, die Soft-
• Technologien und Systeme ware für den Publikationsprozess aus-
• Qualitätsmanagement wählen oder selbst erstellen
• Praxisbeispiele, Checklisten • externe Dienstleister, die eigenverant-
wortlich Aufgaben übernehmen können

Als eine Ergänzung zu den einschlägigen Normen zeichnet sich diese Richt-
linie dadurch aus, dass die genannten Aspekte streng prozessorientiert zu in-
terpretieren sind. Beim Leser wird ein entsprechendes Abstraktionsvermögen
vorausgesetzt, damit er die Sachverhalte und Beispiele auf sein eigenes Ar-
beitsgebiet anwenden kann. Insbesondere muss er die Auswahl der für seine
Der Prozess steht im Aufgabe und Situation anwendbaren Dokumente im Einzelfall selbst bestim-
Vordergrund men. Ziel der Richtlinie VDI 4500 Blatt 4 ist nicht die Vollständigkeit der
Normenverweise und anderer Ausführungsdetails, stattdessen steht die Pro-
zessbetrachtung im Vordergrund.
Grundlage zum Verständnis von Blatt 4 ist die Richtlinie VDI 4500 Blatt 1.
Diese befasst sich mit den Begriffsdefinitionen und rechtlichen Grundlagen
der Technischen Dokumentation. Insbesondere die Abschnitte, die sich mit
den Verantwortlichkeiten und den rechtlichen Voraussetzungen befassen, gel-
ten auch für die Schritte Planen, Gestalten und Erstellen im Dokumentations-
prozess.

1 Anwendungsbereich
Die Inhalte der Richtlinie VDI 4500 Blatt 4 wenden sich an die Ersteller von
Technischer Dokumentation und besonders an die Zielgruppe der Techni-
schen Redakteure, die im klassischen Sinn Externe Technische Dokumenta-
tion erstellen.

1.1 Ihr Nutzen


Wer heute im Unternehmen für Konzeption, Ausführung und Verteilung von
Technischer Dokumentation verantwortlich ist, muss sich damit auseinander-
setzen, welche Arten von Dokumenten benötigt werden und wie diese zu er-
stellen sind. Zusätzlich sind Kenntnisse über die zweckmäßigen Werkzeuge
und über die Qualität von Technischer Dokumentation notwendig.

–4– VDI 4500 Blatt 4 / Part 4


Scope
Your benefit

Part Contents Target group

Part 5: • business managerial aspects • managing directors in terms of


Documentation • optimising of information evaluation of documentation services
process: • and documentation • commercial managers in terms of
economical processes business managerial evaluation
documentation • project-based calculation • technical managers in terms of practica-
• use of internal resources, bility with available or purchased
inclusion of external service resources
providers • product manager or project manager with
• practical examples, checklists respect to cost-efficient integration in the
product lifecycle
• executives who are entrusted with the
creation and coordination of technical
documentation

Part 6: • publishing as part of the • responsible persons who are in charge of


Documentation documentation process the data infrastructure, the documenta-
process: publication • legal aspects tion and the distribution of the documents
• access to information, inter- • experts and management, who select or
faces and standards themselves create software for the publi-
• technologies and systems cation process
• quality management • external service providers, who can
• practical examples, checklists assume duties under their own responsi-
bility

As an addition to the pertinent standards, this guideline is characterised by the


fact that the aforementioned aspects are to be interpreted in a strictly process-
oriented context. It is assumed that the reader has a certain ability to abstract,
so that he can apply the facts and examples to his own area of work. In par-
ticular, he must himself determine the selection of the documents applicable
The process is at the to his task and situation in the individual case. Aim of the guideline VDI 4500
forefront Part 4 is not the completeness of the references to standards and other layout
details; the focus is rather on the process examination.

Basis for the understanding of Part 4 is the guideline VDI 4500 Part 1. This
deals with the term definitions and legal bases of technical documentation. In
particular, the sections that deal with the responsibilities and the legal prereq-
uisites are equally applicable to the steps of planning, layout and creation of
the documentation process.

1 Scope
The contents of the guideline VDI 4500 Part 4 are addressed to the creators of
technical documentation and especially to the target group of technical writ-
ers, who create external technical documentation in the classic sense.

1.1 Your benefit


Whoever is responsible today in the company for the conception, layout and
distribution of technical documentation, must deal with the question as to
which types of documentation are needed and how these are to be created.
Additionally, knowledge of the advantageous tools and about the quality of
technical documentation is needed.

VDI 4500 Blatt 4 / Part 4 –5–


Anwendungsbereich
Was gehört zur Technischen Dokumentation?

Die Richtlinie VDI 4500 Blatt 4 betrachtet das Planen, Gestalten und Erstel-
len von Technischer Dokumentation als Teilprozess im Dokumentationspro-
zess. In der Zielgruppe von Blatt 4 sind in erster Linie Personen, die innerhalb
dieses Prozesses die Technische Dokumentation erstellen, aber auch diejeni-
gen, die Informationen für die Technische Dokumentation liefern oder Teil-
dokumente beistellen.
Interne Technische In jeder Phase des Produktlebenszyklus entsteht Interne Technische Doku-
Dokumentation mentation. Sie verhindert, dass erworbenes Wissen verloren geht und ist
gleichzeitig auch der geforderte aussagefähige Nachweis des Produktherstel-
lers hinsichtlich der Erfüllung der Anforderungen aus den verschiedenen
Rechtsbereichen. Interne Technische Dokumentation stellt die Grundlage für
die darauf aufbauende Externe Technische Dokumentation dar.
Das Benutzen eines Redaktionshandbuchs ermöglicht eine systematische Er-
stellung von Externer Technischer Dokumentation. Dadurch werden die
Dokumentationsprozesse transparent, das Erstellen von Technischer Doku-
mentation wird effizient, und die Dokumente lassen sich in ihrer Qualität ver-
bessern.
Anerkannte Regel der Technik Die Richtlinienreihe VDI 4500 ist eine allgemein anerkannte Regel der Tech-
nik, die wertvolle Hilfestellung und praxisnahe Empfehlungen für das Planen,
Erstellen und Gestalten von Technischer Dokumentation gibt.

1.2 Was gehört zur Technischen Dokumentation?


Die Gesamtheit der Technischen Dokumentation beinhaltet alle technischen
Informationen, die von einem Hersteller/Vertreiber parallel zum Entstehen
und zum Lebensweg eines Produkts dokumentiert werden.
Bild 1 zeigt den Bereich der Technischen Dokumentation und seine Unter-
teilung in Interne Technische Dokumentation und Externe Technische Doku-
mentation. In den beiden Bereichen der Technischen Dokumentation sind
unterschiedliche Aspekte zu dokumentieren:
• Die Interne Technische Dokumentation muss sämtliche Produktentwick-
lungsschritte als Nachweis transparent, reproduzierbar und nachvollzieh-
bar festhalten – von der Produktanalyse bis hin zu den Entsorgungspro-
zessen.
• Die Externe Technische Dokumentation dient der Produktnutzung durch
den Anwender. Die Dokumentenarten und Dokumentationsprozesse kön-
nen vielfältig sein. Marketingunterlagen müssen ebenfalls in die Doku-
mentationsprozesse mit einbezogen werden.
Prozessabweichungen Blatt 4 unterscheidet nur dann zwischen Interner Technischer Dokumentation
und Externer Technischer Dokumentation, wenn die Prozesse voneinander
abweichen.

–6– VDI 4500 Blatt 4 / Part 4


Scope
What constitutes technical documentation?

The guideline VDI 4500 Part 4 regards the planning, layout and creation of
technical documentation as a sub-process within the documentation process.
The target group of Part 4 primarily contains persons who create the technical
documentation within this process, though also persons who deliver informa-
tion for the technical documentation or provide portions of the documents.

Internal technical In each phase of the product lifecycle, internal technical documentation is
documentation created. It prevents acquired knowhow from being lost and is, at the same
time, also the required informative proof by the product manufacturer regard-
ing the fulfilment of the requirements arising from various legal areas. Inter-
nal technical documentation forms the basis for the external technical docu-
mentation which builds upon it.
The use of an editorial manual allows for systematic creation of external tech-
nical documentation. This makes the documentation process transparent, the
creation of technical documentation becomes more efficient and the quality
of the documents can be improved.

Acknowledged rules of The series of guidelines VDI 4500 is a generally acknowledged rule of tech-
technology nology, which provides valuable help and practical recommendations for the
planning, creation and layout of technical documentation.

1.2 What constitutes technical documentation?


The totality of technical documentation consists of all technical information
that is documented by a manufacturer/distributor in parallel with the creation
and lifecycle of a product.
Figure 1 shows the area of technical documentation and its sub-divisions
into internal documentation and external technical documentation. Different
aspects are to be documented in the two areas of technical documentation:

• Internal technical documentation must record in writing all the product


development steps as evidence that is transparent, reproducible and re-
traceable – from the product analysis up to the disposal processes.

• The external technical documentation serves the purpose of product use


by the user. The document types and documentation processes can be di-
verse. Marketing documents must be likewise included in the documenta-
tion processes.
Process deviations Part 4 distinguishes between internal technical documentation and external
technical documentation only if the processes deviate from each other.

VDI 4500 Blatt 4 / Part 4 –7–


Vom Produktlebenszyklus zum Dokumentationsprozess
Was gehört zur Technischen Dokumentation?

Bild 1. Überblick über die Unternehmensdokumentation

2 Vom Produktlebenszyklus zum Dokumentationsprozess


Von der Konzeption bis zur Entsorgung durchläuft ein Produkt eine Vielzahl
von Prozessen. Diese Prozesse stehen in Wechselwirkung mit der Techni-
schen Dokumentation oder beeinflussen sie (siehe Bild 2).
Beispiele von Dokumentenarten finden sich in VDI 4500 Blatt 1. Weiterfüh-
rende Informationen zum Lebenszyklusmodell sind in DIN ISO 15226 zu-
sammengefasst.

–8– VDI 4500 Blatt 4 / Part 4


From the product lifecycle up to documentation process
What constitutes technical documentation?

Figure 1. Overview of company documentation

2 From the product lifecycle up to documentation process


From conception up to disposal, a product undergoes several processes.
These processes are in interaction with the technical documentation or influ-
ence it (see Figure 2).
Examples of document types are given in VDI 4500 Part 1. Continuative in-
formation about lifecycle model is summarised in DIN ISO 15226.

VDI 4500 Blatt 4 / Part 4 –9–


Vom Produktlebenszyklus zum Dokumentationsprozess
Was gehört zur Technischen Dokumentation?

Bild 2. Typische Dokumente/Dokumentationsprozesse im Rahmen des Produktlebenszyklus

– 10 – VDI 4500 Blatt 4 / Part 4


From the product lifecycle up to documentation process
What constitutes technical documentation?

Figure 2. Typical documents/documentation processes in the course of the production lifecycle

VDI 4500 Blatt 4 / Part 4 – 11 –


Dokumentation planen
Dokumentenarten

3 Dokumentation planen
Zur Sicherung der Qualität und zur Erhöhung der Wirtschaftlichkeit emp-
fiehlt sich eine mit dem Produktlebenszyklus abgestimmte Planung der Tech-
nischen Dokumentation.
Die Planung hängt sehr stark von den unternehmens- und produktspezifi-
schen Prozessen ab. Deshalb können die nachfolgend genannten Planungs-
schritte nur Grundüberlegungen für den individuellen Planungsprozess sein.

3.1 Dokumentenarten
Jeder Schritt im Produktlebenszyklus, den ein Produkt oder eine Leistung
durchläuft, steht im Zusammenhang mit einer dafür notwendigen Dokumen-
tenart.
Der Produktlebenszyklus beginnt mit der Produktidee und endet mit der Wie-
derverwertung oder der Entsorgung (siehe auch Richtlinie VDI 4500 Blatt 1,
Bild 2). Es entstehen mit dem jeweiligen Arbeitsschritt verknüpfte oder
schrittübergreifende Dokumente.
Die Dokumente müssen nicht in unmittelbarem zeitlichen Zusammenhang
mit einem Arbeitsschritt stehen, sondern können vor, während, oder – wenn
notwendig – auch nach dem Schritt erstellt werden.
Während des Produktlebenszyklus entstehen sowohl Dokumente für die Ver-
wendung innerhalb des Unternehmens (Interne Technische Dokumentation)
als auch Dokumente, die mit dem hergestellten Produkt oder der erbrachten
Leistung der jeweiligen Zielgruppe zur Verfügung stehen (Externe Techni-
sche Dokumentation). Siehe dazu auch Richtlinie VDI 4500 Blatt 1, Ta-
belle 1 und Tabelle 2.
Beispiele für die Zuordnung von Dokumenten:
• „Produktion“ im Produktlebenszyklus: interne Dokumente
• „Montage“ im Produktlebenszyklus: interne und externe Dokumente
• „Bedienung“ im Produktlebenszyklus: externe Dokumente

3.2 Planungsschritte
Stellvertretend für die Vielzahl möglicher Planungsschritte werden im Fol-
genden beispielhaft einige herausgegriffen und beschrieben.
Verantwortlichkeiten Das Unternehmen muss durch interne Verfahrensfestlegungen (z.B. Redakti-
onshandbuch, Konstruktionshandbuch) regeln, wer für die Richtigkeit und
Vollständigkeit der Unterlagen verantwortlich ist, die die Grundlage für die
Technische Dokumentation darstellen. Ebenfalls muss festgelegt sein, wie die
Unterlagen rechtzeitig für die nachfolgenden Dokumentationsprozesse in
ausreichender Qualität verfügbar gemacht werden.
Analysen Eine rechtlich einwandfreie und anwendergerechte Technische Dokumenta-
tion setzt voraus, dass
• die Zielgruppen bekannt sind,
• das Produkt analysiert wird,
• die Maßnahmen aus Risikoanalyse und Risikobewertung in Produktent-
wicklung und -dokumentation umgesetzt sind,
• die einschlägigen Normen aus der Normenrecherche in Produktentwick-
lung und -dokumentation beachtet werden und
• die einschlägigen Rechtsvorschriften, insbesondere aus dem Produkt-
sicherheitsrecht, beachtet werden.

– 12 – VDI 4500 Blatt 4 / Part 4


Planning of documentation
Document types

3 Planning of documentation
For ensuring quality and increasing economic efficiency, it is recommended
to attune the planning of technical documentation to the product lifecycle.

The planning depends greatly on the company and product-specific proc-


esses. That is why the following planning steps can only be construed as basic
considerations for the individual planning process.

3.1 Document types


Each step in the product lifecycle, which a product or a service undergoes, is
associated with a document type necessary for it.

The product lifecycle starts with the product idea and ends with the recycling
or disposal (see also guideline VDI 4500 Part 1, Figure 2). Documents either
associated with the respective step or spanning several steps are created.

The documents need not necessarily be directly connected to the work step in
terms of time, but can be created before, during or – where necessary – even
after the step.
During the product lifecycle, documents are created both for use within the
company (internal technical documentation) as well as for making available
to the respective target group with the manufactured product or the rendered
service (external technical documentation). See also guideline VDI 4500
Part 1, Table 1 and Table 2.

Examples for the classification of documents:


• “Production” in the product lifecycle: internal documents
• “Assembly” in the product lifecycle: internal and external documents
• “Service” in the product lifecycle: external documents

3.2 Planning steps


A few examples have been picked out and described in the following, as rep-
resentative samples of the multiplicity of possible planning steps.
Responsibilities Using internal procedural specifications (e.g. editorial guide, design guide),
the company must regulate as to who shall be responsible for the correctness
and completeness of the documents that form the basis for the technical doc-
umentation. Likewise, it must be specified as to how the documents shall be
made available in sufficient quality and on time for the subsequent documen-
tation processes.
Analyses A legally flawless and user-friendly technical documentation presupposes
that
• the target groups are known,
• the product will be analysed,
• the measures resulting from risk analysis and risk estimation are imple-
mented in the product development and documentation,
• the pertinent standards resulting from the standards research are taken into
account in the product development and documentation, and
• the pertinent legal provisions, in particular related to the law on product
assurance, are considered.

VDI 4500 Blatt 4 / Part 4 – 13 –


Dokumentation planen
Planungsschritte

Bild 3. Produktlebenszyklus und die den einzelnen Phasen zugeordneten Dokumente

– 14 – VDI 4500 Blatt 4 / Part 4


Planning of documentation
Planning steps

Figure 3. Product lifecycle and the documents assigned to the individual phases

VDI 4500 Blatt 4 / Part 4 – 15 –


Dokumentation planen
Planungsschritte

Welche Abteilungen oder welche Personen innerhalb der Betriebsorganisa-


tion eines Unternehmens dafür zuständig und verantwortlich sind, dass die
Dokumentationsabteilung die notwendigen Daten und Unterlagen rechtzeitig
und vollständig erhält, hängt vom Unternehmen und dessen Aufbauorganisa-
tion ab.
Einen beispielhaften Überblick über Zulieferungen aus Produktmanagement
und Produktentwicklung als Voraussetzung für eine fachgerechte Technische
Dokumentation gibt Bild 4.

Bild 4. Zulieferungen für die Technische Dokumentation aus Produktmanagement und Produktentwick-
lung (Hinsichtlich der Kosten- und Terminrahmen ist die Technische Redaktion in den Abstimmungspro-
zess einzubeziehen.)

Ablaufplanung Unabhängig von der Dokumentenart und vom Produkt folgt der Dokumenta-
tionsprozess innerhalb der Technischen Redaktion bestimmten Abläufen, wie
in Bild 5 beispielhaft dargestellt (gezeigt sind nur die wesentlichen Phasen):

Diese Prozessschritte begleiten das Produkt über den gesamten Produkt-


lebenszyklus und stellen einen kontinuierlichen Iterationsprozess dar, der die
Fortentwicklung des Produkts selbst sowie die Veränderungen aller Rand-
bedingungen widerspiegelt.
Freigegebene Fassungen sind so zu archivieren, dass der Hersteller anhand
der Dokumente den Nachweis der Sorgfaltspflicht jederzeit während des Pro-
duktlebenszyklus erbringen kann.

– 16 – VDI 4500 Blatt 4 / Part 4


Planning of documentation
Planning steps

Which departments or which persons within the plant organisation of a com-


pany are competent and responsible for the timely and complete receipt of the
necessary data and documents by the documentation department, depends on
the company and its organisational structure.

An exemplary overview of the deliveries from product management and


product development as a prerequisite for professional technical documenta-
tion is given in Figure 4.

Figure 4. Deliveries for technical documentation from product management and product development
(The technical editorial department must be included in the coordination process in respect of the costs
and time frame.)

Process flow planning Independent of the document type and product, the documentation process
within the technical editorial department follows certain operational se-
quences, as represented by way of example in Figure 5 (only the essential
phases are shown):
These process steps accompany the product along the entire product lifecycle
and represent a continuous iteration process, which reflects the progressive
development of the product itself as well as the changes to all the parameters.

Approved versions are to be archived such that the manufacturer can furnish
proof of due diligence at all times during the product lifecycle with the help
of the documents.

VDI 4500 Blatt 4 / Part 4 – 17 –


Dokumentation planen
Planungsschritte

Bild 5. Dokumentationsprozess mit typischen Abläufen innerhalb der Technischen Redaktion (Beispiel)

Zielgruppenanalyse Die Zielgruppenanalyse ist vom Hersteller durchzuführen und zu dokumen-


tieren. Sie betrachtet den oder die Nutzer der Technischen Dokumentation
und beantwortet im Schwerpunkt die Fragen:
• Welche Zielgruppe nutzt die Technische Dokumentation?
• Für welchen Kulturkreis/welches Land wird die Technische Dokumenta-
tion erstellt?
• Über welche Qualifikationen, Erfahrungen und Kenntnisse verfügt die
Zielgruppe?
• Welche Tätigkeiten kann und darf die jeweilige Zielgruppe aufgrund ihrer
Qualifikation durchführen?

– 18 – VDI 4500 Blatt 4 / Part 4 Alle Rechte vorbehalten © Verein Deutscher Ingenieure e.V., Düsseldorf 2011
Planning of documentation
Planning steps

Figure 5. Documentation process with typical process flows within the technical editorial department
(example)

Target group analysis The target group analysis must be conducted and documented by the manu-
facturer. It considers the user(s) of the technical documentation and focuses
on answering the questions:
• Which target group uses the technical documentation?
• For which cultural circle/which country is the technical documentation
being created?
• What qualifications, experiences and knowledge does the target group
possess?
• Which activities can and may the respective target group perform based
on its qualifications?

All rights reserved © Verein Deutscher Ingenieure e.V., Düsseldorf 2011 VDI 4500 Blatt 4 / Part 4 – 19 –
Dokumentation planen
Planungsschritte

• Unter welchen Bedingungen und in welcher Situation werden das Produkt


und die zugehörige(n) Benutzerinformation(en) eingesetzt?
• Welche Informationen dürfen nicht kommuniziert werden?
• Welche Informationen müssen nicht kommuniziert werden?
Beispiele für Zielgruppen Interner Technischer Dokumentation sind:
• Konstrukteur/Entwickler
• Projektleiter
• Mitarbeiter der Qualitätssicherung
• Führungskräfte
Beispiele für Zielgruppen Externer Technischer Dokumentation sind:
• Betreiber
• (End-)Anwender
• Schulungspersonal
• Wartung- und Servicepersonal
• Personal für die fachgerechte Demontage und Entsorgung
• Vertriebspersonal
Zur zielgerichteten Auswertung der Analysedaten bei der Zielgruppenana-
lyse haben sich zwei Methoden bewährt: Wer-macht-was-Matrix und Per-
sona-Methode.
Es ist zweckmäßig, sich zunächst einen Gesamtüberblick über Nutzer, Doku-
mentenarten und Handlungen mittels der Wer-macht-was-Matrix zu verschaf-
fen. Die Persona-Methode kann anschließend den Technischen Redakteur da-
bei unterstützen, Einzeldokumente zielgruppenorientiert zu strukturieren, zu
texten und die Inhalte zu visualisieren.
Diese Vorgehensweise empfiehlt sich sowohl für die Interne Technische
Dokumentation als auch für die Externe Technische Dokumentation.
Wer-macht-was-Matrix Die Methode der Wer-macht-was-Matrix führt zu einer Klassifikation der
Nutzer hinsichtlich ihrer Tätigkeiten und typischen Erfahrungen mit dem be-
treffenden Produkt. Dazu werden die durchzuführenden Tätigkeiten über den
gesamten Produktlebenszyklus erfasst und den typischen Ausführenden zu-
geordnet. Daraus ergeben sich im Idealfall die geforderten Sachinhalte für die
zielgruppenbezogenen Dokumentenarten. Der Vorteil dieser Methode ist die
eindeutige Zuordnung der Aufgaben zu den Nutzern und die daraus folgende
Klassifizierung der Dokumente.
Tabelle 1 zeigt vereinfacht an einem konkreten Beispiel, dass man aus einer
Wer-macht-was-Matrix spaltenweise die Sachinhalte für die verschiedenen
Benutzergruppen entnehmen kann. Daraus ergeben sich beispielsweise die
Anleitungskapitel für den Bediener an der Fachausgabe.
Eine chronologische Darstellung der Tätigkeiten und Nutzer ist zu diesem
Zeitpunkt noch nicht wichtig.
Persona-Methode Aus dem Ergebnis der Zielgruppenanalyse leitet man einen idealtypischen
Benutzer des Produkts ab, den man mit allen Eigenschaften beschreibt:
• Alter
• Geschlecht
• Bildung
• Interessen (auch private)
• Benutzungsverhalten
• und weitere mehr

– 20 – VDI 4500 Blatt 4 / Part 4


Planning of documentation
Planning steps

• Under which conditions and in which situation are the product and the re-
spective user information used?
• Which information may not be communicated?
• Which information need not be communicated?
Examples of target groups of internal technical documentation are:
• designer/developer
• project manager
• employees of quality assurance
• managers
Examples of target groups of external technical documentation are:
• operators
• (end-)users
• training personnel
• maintenance and servicing personnel
• personnel for professional dismantling and disposal
• distribution personnel
For the purposeful evaluation of analysis data during target group analysis,
two methods have proved their worth: who-makes-what matrix and persona
method.
It is advisable to first obtain an overall overview of the users, document types
and actions using the who-makes-what matrix. The persona method can sub-
sequently be used to support the technical writers in structuring, content writ-
ing and visualising the contents of individual documents such that they are
target group oriented.
This procedure is recommended both for internal technical documentation as
well external technical documentation.
Who-makes-what matrix The method of who-makes-what matrix leads to a classification of the users in
respect of their activities and typical experiences with the concerned product.
In addition, the activities to be carried out over the entire product lifecycle are
compiled and are assigned to the typical executives. In ideal case, this results
in the required factual contents for the target group oriented document types.
The advantage of this method is the explicit assignment of the tasks to the us-
ers and the resultant classification of the documents.

Table 1 shows in a simplified form, using a concrete example, that the fac-
tual contents for the various user groups can be derived column-by-column
from a who-makes-what matrix. The user guide chapters for the user at the
collection tray, for instance, follow from these.
A chronological representation of the activities and users is not yet important
at this moment.
Persona method From the result of the target group analysis, an ideal type user of the product
is derived, who is described with all properties:
• age
• gender
• education
• interests (even private)
• use pattern
• and the like

VDI 4500 Blatt 4 / Part 4 – 21 –


Dokumentation planen
Planungsschritte

Tabelle 1. Musterbeispiel für die Wer-macht-was-Matrix einer Briefsortieranlage


Maschinenführer Bediener Wartungs- Konfigurations-
Fachausgabe techniker techniker

Parameter für X X (Grund-


OCR einstellen („Fine tuning“) konfiguration)

Vorbeugende X (tägliche X (Reparaturen,


Instandhaltung Wartungsarbeiten) Kundendienst)

Steuerkonsole X X X (Tastenzuord-
bedienen (bedienen) (Fehler prüfen) nung definieren)

Fehler im X (im Magazin- X (im Ausgabe-


Brieflauf beheben bereich) fachbereich)

Briefe in Standard- X (im Ausgabe-


behälter füllen fachbereich)
Briefe in X (im Magazin-
Magazin einfüllen bereich)

Der Vorteil eines solchen detaillierten Benutzerprofils ist, dass dieser ideal-
typische Benutzer, dem man sogar einen Namen zuordnet, vor dem geistigen
Auge des Technischen Redakteurs so visualisiert wird, dass er nicht mehr an-
onym in der abstrakten Benutzerzielgruppe untergeht. Es entsteht eine nahezu
persönliche Beziehung zwischen dem imaginären Benutzer und dem Techni-
schen Redakteur.
Vorgaben und Forderungen Alle produktspezifischen und anwendungsbezogenen Forderungen an die
Technische Dokumentation aus Gesetzen, Verordnungen, Vorschriften, tech-
nischen Normen, Richtlinien, aber auch aus Verträgen müssen vollständig re-
cherchiert und erfasst werden.
Neben direkten Anforderungen von Normen an die Externe Technische
Dokumentation sind darüber hinaus auch Informationen aus produktspezifi-
schen Fachnormen hinsichtlich Gebrauch und Wartung zu berücksichtigen.
Sowohl Lastenheft als auch Pflichtenheft oder Leistungsbeschreibung des
Produkts beinhalten in der Regel Anforderungen an die Technische Doku-
mentation und benennen unter anderem die Zielgruppen für die jeweiligen
Dokumente.
Es empfiehlt sich, alle rechtlichen, technischen und vertraglichen Forderun-
gen – nach Prioritäten geordnet – in Checklisten aufzuführen.
Risikoanalyse und Durch Risikoanalyse und Risikobewertung werden die Restrisiken ermittelt,
Risikobewertung die für die spezifische Tätigkeit an dem oder in der Nähe des Produkts nach
Anwendung von Schutzmaßnahmen verbleiben. Das sind die Risiken, die
durch Konzeptänderung, durch konstruktive Maßnahmen, Vorrichtungen (un-
mittelbare und mittelbare Sicherheitstechnik) und organisatorische Maßnah-
men nicht auszuschließen sind. Die Informationen über Restgefahren fließen
unmittelbar in die Externe Technische Dokumentation ein. Die Externe Tech-
nische Dokumentation darf nicht dazu missbraucht werden, entwicklungs-
technische und konstruktive Mängel auszugleichen.
Gefährdungen und Risiken werden beispielsweise im Fall von Produkten, die
der Europäischen Maschinenrichtlinie (2006/42/EG) unterliegen, durch den
Konstrukteur der Maschine identifiziert bzw. bewertet.
Produktanalyse Die Produktanalyse liefert die Anforderungen an die Inhalte der Technischen
Dokumentation, damit der Anwender das Produkt effizient nutzen kann.
Grundlagen für die Produktanalyse sind:
• bestimmungsgemäße Verwendung des Produkts
• Fehlgebrauch

– 22 – VDI 4500 Blatt 4 / Part 4


Planning of documentation
Planning steps

Table 1. Paradigm for a who-makes-what matrix of a letter sorting system


Machine operator User of Customer Configuration
collection tray engineer engineer

Setting the para- X X (basic


meters for OCR (“fine tuning” configuration)

Preventive X (daily X (repair, cus-


maintenance maintenance jobs) tomer service)

Using the X (using) X X (defining the


control panel (checking errors) key assignments)

Repairing the error in X (in the X (in the collec-


letter run magazine area) tion tray area)

Filling the letters in X (in the collec-


standard containers tion tray area)
Filling the letters in X (in the
the magazine magazine area)

The advantage of such a detailed user profile is that this ideal type user, who
is even assigned a name, is visualised in the mind’s eye of the technical writer
such that he no longer sinks into the anonymous oblivion of the abstract target
user group. A nearly personal relationship is forged between the imaginary
user and the technical writer.

Specifications and All product-specific and use-oriented requirements on technical documenta-


requirements tion based on laws, ordinances, regulations, technical standards, guidelines as
well as contracts must be fully researched and compiled.

In addition to direct requirements of external technical documentation in


terms of standards, information from product-specific technical standards
pertaining to use and maintenance must also be considered.
Both the tender specifications as well as the functional specifications or prod-
uct specifications, as a rule, contain requirements on technical documentation
and name, among other things, the target group for the respective documents.

It is recommended to list all the legal, technical and contractual requirements


– according to priorities – in checklists.
Risk analysis and Risk analysis and risk estimation serve to determine residual risks, that are
risk estimation present for a specific activity on or with a product after the application of pro-
tective measures. These are the risks that cannot be excluded through concept
change, design and engineering measures, devices (direct or indirect safety
technology) and organisational measures. The information about residual
risks flows directly into the external technical documentation. The external
technical documentation may not be misused to balance deficiencies in de-
sign and development.

Hazards and risks are, for instance, identified and/or evaluated by the engi-
neer of the machine in case of products that are subject to the European Ma-
chinery Directive (2006/42/EC).
Product analysis The product analysis delivers the requirements in terms of content of the tech-
nical documentation so that the user can use the product efficiently.
Basic principles for the product analysis are:
• use of the product for the intended purpose and according to instructions
• misuse

VDI 4500 Blatt 4 / Part 4 – 23 –


Dokumentation planen
Daten aufbereiten

• Funktionen, Arbeitsweisen und Handhabungen


• mögliche (Rest-)Gefahren
• erforderliche Wartungs- und Instandhaltungsmaßnahmen
Diese Informationen stellen die Fachabteilungen für Marketing, Entwick-
lung, Konstruktion, Vertrieb, Qualitätssicherung und Kundendienst zur Ver-
fügung.
Zusätzlich müssen Informationen in die Produktanalyse einfließen aus
• Produktbeobachtung im Unternehmen und bei Kunden,
• Anwendertests,
• dokumentierten Gewährleistungsansprüchen und Kulanzleistungen,
• Schulungen und Einweisungen unterschiedlicher Mitarbeiter/Anwender-
gruppen und
• Kundendienst- und Serviceberichten.
Informationsverwaltung planen Vor und während des Produktlebenszyklus entsteht eine Vielzahl von Daten
und Informationen. Um darauf einen gezielten Zugriff zu gewährleisten,
muss auf folgende Punkte geachtet werden:
• Infrastruktur und Ressourcen festlegen und bereitstellen
• Ablage- und Speicherorte definieren
• Dateiformate festlegen
• Zugriffsrechte festlegen
• Glossar und Versionierung definieren
• Ablagestrukturen und Suchkritierien festlegen
• Aufbewahrungs- und Vernichtungsvorschriften anwenden
• Rückverfolgbarkeit gewährleisten
• (Langzeit-)Archivierung planen
• Verfügbarkeit sicherstellen

3.3 Daten aufbereiten


Aus der Vielzahl der gewonnenen Daten müssen die für die Zielgruppen und
Dokumentationsarten erforderlichen Informationen ausgewählt und aufberei-
tet werden.
Quellen Informationsquellen für Technische Dokumentation sind z.B. technische
Unterlagen, Protokolle, Verträge und Notizen genauso wie E-Mails. Informa-
tionen werden aber auch durch Gespräche übermittelt.
Als Vorarbeit für Gespräche ist es sinnvoll, einen detaillierten Rechercheplan
auszuarbeiten und sich bewährter Methoden- und Fragetechniken zu bedie-
nen. Gut vorbereitete Interviews lassen sich effizient durchführen und liefern
vollständige und eindeutige Informationen.
Dokumente und Daten können in Unternehmen in sehr unterschiedlichen
Formen und Formaten vorliegen. So unterscheiden sich Dokumente aus der
Entwicklung von den Dokumenten der Marketingabteilung, auch hinsichtlich
der Art, wie sie archiviert sind. Dokumente und Daten können in Papierver-
sion und elektronischer Form vorliegen.
Informationen vereinheitlichen Aus der Unterschiedlichkeit der Quellen und der Archivierung heraus ent-
steht die Notwendigkeit, Daten und Dokumente zu prüfen, zu selektieren und
zu sichern. Die Informationen sollten hinsichtlich Inhalt und Format struktu-
riert und vereinheitlicht werden. Abhängig von der anschließenden Art der
Nutzung kann die Aufbereitung erheblichen Aufwand bedeuten. Zum Bei-
spiel erfordert die Ablage in relationalen Datenbanken das Umsetzen der Da-

– 24 – VDI 4500 Blatt 4 / Part 4


Planning of documentation
Preparation of data

• functions, working methods and handling


• possible (residual) dangers
• required maintenance and servicing measures
This information is made available by the departments for marketing, devel-
opment, design, distribution, quality assurance and customer service.

Additionally, information must flow into the product analysis from


• product monitoring within the company and at the customer’s,
• user tests,
• documented warranty claims and ex-gratia payments,
• trainings and briefings of various employees/user groups and customer
service and
• service reports.
Planning of information Before and during the product lifecycle, a multiplicity of data and information
management is created. To ensure selective access to these, the following points must be
borne in mind:
• determining and providing the infrastructure and resources
• defining storage places and filing locations
• specifying the file formats
• specifying the access rights
• defining the glossary and versioning
• specifying the filing structures and search criteria
• applying the regulations pertaining to preservation and destruction
• ensuring that there is reproducibility
• (long-term) planning of archiving
• ensuring of availability

3.3 Preparation of data


Out of the multiplicity of acquired data, the information for the target groups
and documentation types must be selected and prepared.

Sources Sources of information for technical documentation are e.g. technical docu-
ments, records, contracts and notes as well as e-mails. Information is, how-
ever, communicated through verbal discussions as well.
As preparatory work for talks/discussions, it is advisable to develop a detailed
and researched plan and to use proven methods and questioning techniques.
Well prepared interviews can be conducted efficiently and deliver complete
and explicit information.
Documents and data can be available in a company in various forms and for-
mats. Thus, documents from the development department vary from docu-
ments from the marketing department, even where archiving is concerned.
Documents and data can be available in electronic form or in hard copy.

Standardising of information The variety of sources and archiving types make it necessary to check, select
and protect data and documents. The information should be structured and
standardised in terms of content and format. Depending upon the subsequent
usage type, the preparation can involve a lot of effort. For instance, the filing
in relational databases requires the conversion of the data into electronic for-
mat so that they can be automatically imported and assigned.

VDI 4500 Blatt 4 / Part 4 – 25 –


Dokumentation gestalten
Daten aufbereiten

ten in elektronische Form derart, dass sie automatisiert eingelesen und zuge-
ordnet werden können.
Anzustreben ist immer eine identische Struktur über alle Dokumente hinweg.
Hier muss – wegen der Unterschiedlichkeit der Dokumente – darauf geachtet
werden, dass die Modularität nicht zu tief greift.
Ähnliches gilt auch für die Struktur der Daten. Historisch gewachsene Daten-
bestände und der Einsatz unterschiedlichster EDV-Systeme produzieren eine
Vielzahl unterschiedlicher Datenformate. Auch hier sind die Vereinheitli-
chung der Datenbestände und die Konzentration auf wenige, universell ver-
wendbare Formate oberstes Gebot.
Standardisierte Prozesse, Wichtig zum Einsatz aller nachfolgenden Techniken sind immer stan-
Dokumente und Daten! dardisierte Prozesse, standardisierte Dokumente und standardisierte
Daten!
Erst nach der Strukturierung von Dokumenten und Daten mit dem Ziel eines
standardisierten Datenbestands kommt die Systemtechnik zum Einsatz.
Nach der Festlegung,
• welche Art von Dokumenten benötigt wird,
• wie hoch der Grad der Automatisierung sein soll und
• welche Anzahl an Dokumenten erstellt werden soll,
erfolgt die Auswahl eines geeigneten Systems. Erst jetzt kann die Entschei-
dung für ein DTP-System oder ein Redaktionssystem erfolgen.
Beim Einsatz aller Systeme ist darauf zu achten, dass
• ein schneller und direkter Zugriff auf die Informationen gewährleistet ist,
• die Daten oder die daraus erstellten Dokumente den jeweiligen Vorgaben
entsprechend langzeitig archiviert werden können,
• die Daten oder die daraus erstellten Dokumente jederzeit – auch in ferner
Zukunft innerhalb des Produktlebenszyklus – zugänglich sind, um sie im
Bedarfsfall einzusehen und gegebenenfalls zu überarbeiten,
• die Rückverfolgbarkeit von Änderungen sichergestellt ist und
• ein langlebiges Datenformat gewählt wird.

4 Dokumentation gestalten
Die Externe Technische Dokumentation hat sich als eigenständige Disziplin
in der Technik etabliert. Parallel dazu ist das Angebot an guter Fachliteratur
beständig gewachsen. In Normen, Grundlagenwerken und in Schriften zu
speziellen Themen der Technischen Dokumentation wird der Stand der
Methodik umfassend und qualifiziert dargestellt.
Die Gestaltung Technischer Dokumentation trägt entscheidend zum Nutzen
und erfolgreichen Benutzen bei. Aus einer Vielzahl von Gestaltungselemen-
ten ergeben sich mannigfaltige Kombinationsmöglichkeiten, mit denen sich
nahezu alle aufgabenspezifischen Anforderungen aus der Praxis und aus den
Rechtsbereichen erfüllen lassen. In dieser Richtlinie werden die Schwer-
punkte vorgestellt, die bei der Festlegung der Gestaltung von Externer Tech-
nischer Dokumentation zu berücksichtigen sind. Die Einsatzmöglichkeiten
und ihre Wirkung sind in der einschlägigen Fachliteratur ausführlich behan-
delt. Auf Ausführungsdetails wird daher in dieser Richtlinie nicht speziell
eingegangen.

– 26 – VDI 4500 Blatt 4 / Part 4


Layout of documentation
Preparation of data

The aim is always to achieve an identical structure across all documents. At


this juncture – due to the variety of documents – care must be taken that the
modularity of structure is not too pervasive.
This is equally applicable to the structure of the data. Historically grown data
bases and the use of various EDP systems produce a multiplicity of various
data formats. Here, as well, the standardisation of data bases and concentration
on a few, universally applicable formats is of paramount importance.

Standardised processes, Important for the use of all the following techniques are always standard-
documents and data! ised processes, standardised documents and standardised data!

Only after the structuring of documents and data with the aim of a standard-
ised database is the system technique applied.
The specification
• as to which type of documents is needed,
• how high the degree of automation should be and
• what quantity of documents should be created
is followed by the selection of an appropriate system. Only now can the deci-
sion in favour of a DTP system or a content management system be taken.
While using all the systems, care must be taken that
• quick and direct access to the information is guaranteed,
• the data or the documents created from the data can be archived in the
long term according to the respective specifications,
• the data or the documents created from the data are accessible at all times
– even in the distant future within the product lifecycle – so that they can
be inspected in case of need and possibly revised,
• the reproducibility of changes is ensured and
• a long-lasting database is selected.

4 Layout of documentation
External technical documentation has established itself as a self-contained
discipline in technology. The offer of good technical literature has consist-
ently grown in parallel to this development. In standards, fundamental ap-
proaches and in literature on special topics of technical documentation, the
state of methodology is comprehensibly and qualitatively described.
The layout of technical documentation contributes decisively to the benefit
and successful use of the documentation. A variety of layout elements present
diverse possibilities of combination, with which nearly all task-specific re-
quirements related to practical and legal aspects, can be fulfilled. This guide-
line introduces the focuses that must be considered while specifying the lay-
out of external technical documentation. The usage options and their effects
are treated in detail in the pertinent technical literature. Therefore, layout de-
tails are not dealt with especially in this guideline.

VDI 4500 Blatt 4 / Part 4 – 27 –


Dokumentation gestalten
Grundsätze

4.1 Grundsätze
Eine gute Gestaltung ist einerseits abgestimmt auf das Produkt selbst und
zum anderen auf die Zielgruppe und auf die ihr zu vermittelnden Informatio-
nen.
Das Gestaltungskonzept fußt auf den Ergebnissen der Produkt- und Zielgrup-
penanalyse, die im Idealfall auch Aussagen zur mentalen Situation und zu den
Umgebungsbedingungen des Nutzers sowie zu der Bedeutung von Gestal-
tungselementen in dessen kulturellem Umfeld liefert. Anforderungen, die
sich durch das Ausgabemedium und den Aufbewahrungsort der Technischen
Dokumentation ergeben, sind ebenfalls zu berücksichtigen.
Zielgerichtet zu gestalten bedeutet, die Informationsinhalte richtig und
schnell erfassbar zu machen. Eine klare und logische Gliederung des Inhalts
wird gestalterisch durch optische Strukturmittel verdeutlicht. Von grundle-
gender Bedeutung sind Wahrnehmung und Verständlichkeit von Texten und
Abbildungen.
Produktgröße und Platzverhältnisse sind zu berücksichtigen, wenn die Ex-
terne Technische Dokumentation direkt auf dem Produkt angebracht werden
muss. Sie muss anwendungsbezogen für die gesamte Nutzungsdauer verfüg-
bar bleiben.
Die Gestaltungsrichtlinien müssen – je nach Einbindung externer Stellen – in
jeweils aktueller Form an externe Dienstleister, Übersetzer und Bauteilliefe-
ranten weitergeleitet werden. Sie dürfen keinen Spielraum für individuelle
Gestaltung lassen. Aber auch im Unternehmen sind die Gestaltungsrichtli-
nien zwingend zu berücksichtigen; sie können in Form von Redaktionshand-
büchern dokumentiert sein.
Die Externe Technische Dokumentation ist stets auch eine Außendarstellung
des Unternehmens und transportiert somit die Unternehmensphilosophie.
Aus diesem Grund sollte das Gestaltungskonzept mit dem Corporate Design
abgestimmt sein.

4.2 Layout, Farbe, Text und Bild


Layout Die Text- und Bildgestaltung prägt wesentlich die optische Struktur eines Do-
kuments. Sie wird durch das Layout festgelegt. Im Allgemeinen sind das Lay-
out eines Dokuments und das Layout seiner einzelnen Seiten unterschiedlich.
Die optische Strukturierung ist Orientierungshilfe, z.B. durch Register, In-
halts- und Stichwortverzeichnisse. Elemente wie Format, Überschriften, Ab-
sätze, Leerräume, Tabellen, Marginalien, Signale und Farben verdeutlichen
die zu erklärenden Zusammenhänge.
Bilder sind immer dann sinnvoll, wenn sich ein Zusammenhang durch eine
Abbildung schneller oder genauer erklären lässt als durch Text allein. Gene-
rell sollen sich Text und Bild gegenseitig unterstützen. Dies kommt auch den
Wahrnehmungsfähigkeiten des Menschen zugute, der dann eine besonders
gute Aufnahmefähigkeit von Informationen zeigt, wenn sich visuelle Ele-
mente und textliche Anleitungen ergänzen.
Farbe Farbe als Gestaltungsmerkmal spielt in der Technischen Dokumentation eine
zunehmende Rolle. In der Vergangenheit war die Verwendung von farbigen
Gestaltungsmerkmalen in Verbindung mit dem Ausgabemedium Print ein
wesentlicher Kostenfaktor. Durch moderne Multimedia- und Bildschirm-
anwendungen sowie durch die Fortentwicklungen im Reproduktionsbereich
Medien (z.B. kostengünstige Farbdrucker am Arbeitsplatz) hat sich die Ver-
wendung von farbigen Gestaltungsmerkmalen in vielen Bereichen bereits
durchgesetzt.

– 28 – VDI 4500 Blatt 4 / Part 4


Layout of documentation
Basic principles

4.1 Basic principles


A good layout is, on the one hand, fine-tuned to the product and, on the other
hand, to the target group and to the information to be communicated to it.

The layout concept is based on the results of the product and target group
analysis, which – in the ideal case – delivers information even about the men-
tal state and the environmental conditions of the user as well as about the sig-
nificance of layout elements in the user’s cultural environment. Requirements
that result from the output medium and the place of storage of the technical
documentation must be likewise taken into account.
Purposeful layout means to make the informative content quickly and cor-
rectly ascertainable. A clear and logical structuring of the content is illus-
trated creatively through optical structural devices. Of fundamental impor-
tance are perception and comprehension of texts and illustrations.

Product size and space ratios must be taken into account, if the external tech-
nical documentation has to be applied directly on the product. It must be use-
oriented and remain available for the entire useful life of the product.

Depending upon the inclusion of external offices, the layout guidelines must
be forwarded to external service providers, translators and sub-suppliers in
the currently valid version. They should leave no leeway for individual lay-
out. Even within the company, the layout guidelines absolutely must be taken
into account; they can be documented in the form of editorial manuals.

External technical documentation is always also an external representation of


the company and therewith transports the company philosophy. That is the
reason why the layout concept should be harmonised with the corporate de-
sign.

4.2 Layout, colour, text and image


Layout The text and image design characterises the optical structure of a document
significantly. It is determined by the layout. In general, the layout of a docu-
ment and the layout of its individual pages are different.
The optical structuring is an orientation aid, e.g. with the help of register, list
of contents and keywords. Elements such as format, headings, paragraphs,
blank spaces, tables, margins, signals and colours clarify the contexts to be
explained.
Images are always advisable if a context is explained quicker and more accu-
rately through an illustration than through text alone. In general, text and im-
age should support each other. This also benefits the cognitive faculties of
man, who shows an especially high receptiveness for information, if textual
instructions are supported by visual elements.

Colour Colour as a design feature plays an increasing role in technical documenta-


tion. In the past, the use of colour design features in combination with the
print output medium was a significant cost factor. Due to modern multimedia
and display screen applications as well as due to the advancements in the re-
production segment of media (e.g. cost-effective colour printer at work-
place), the use of colour design features has caught on in many areas.

VDI 4500 Blatt 4 / Part 4 – 29 –


Dokumentation erstellen
Ausgabemedium

Text Für die textliche Gestaltung sind zum einen das äußerliche formale Erschei-
nungsbild und zum anderen die inhaltliche sprachliche Gestaltung festzule-
gen.
Die inhaltliche Gliederung orientiert sich am Zweck der Externen Techni-
schen Dokumentation und hat demnach den Blickwinkel auf das Produkt, auf
eine zu lösende Aufgabe oder die Abfolge der Lernschritte des Nutzers ge-
richtet.
Bei sensiblen Textarten (z.B. Sicherheitshinweise) ist auf eine konsistente
Formulierung besonders zu achten.
Bild Als wichtige Verständnishilfen müssen Bilder in der Technischen Dokumen-
tation deutlich und eindeutig sein und sich auf das Wesentliche beschränken.
Sie müssen den Text in jedem Fall ergänzen und, dem Handlungsablauf ent-
sprechend, im Text logisch eingebunden sein.
Als Bilder gelten Diagramme ebenso wie Piktogramme, Symbole, Illustrati-
onen und Fotos. Zutreffende Normenwerke, der Informationszweck und die
Zielgruppe bestimmen in erster Linie, in welcher Art eine Information visua-
lisiert werden soll.
Im Hinblick auf notwendige Übersetzungen sollten Bilder keinen Text enthal-
ten.

4.3 Ausgabemedium
Von erheblicher Bedeutung ist die rechtzeitige Auswahl der späteren Medien
zum Verteilen und zum Gebrauch. Die Gestaltungsregeln für die Ausgabe-
medien Print, Bildschirm und Multimedia sind unterschiedlich und in der
Regel nicht miteinander kompatibel .
So ist bei der Ausgabe von Text zu berücksichtigen, dass im Vergleich zum
Bildschirm die Lesegeschwindigkeit von Papierdokumenten um bis zu 30 %
höher ist. Papierlesen wird zudem als weniger anstrengend empfunden, und
der Leser kann vom Gelesenen mehr wiedergeben. Die Beurteilung der Les-
barkeit von Bildschirmtexten wird stärker von der Motivation und Erwartung
der Benutzer beeinflusst, als dies bei Papierdokumenten der Fall ist.
Die Entwicklung eines Gestaltungskonzepts ist besonders anspruchsvoll,
wenn Technische Dokumentation für die Ausgabe in mehreren Medien vor-
gesehen ist (Cross-Media-Publishing).

5 Dokumentation erstellen
Die Inhalte dieses Abschnitts beziehen sich hauptsächlich auf Externe Tech-
nische Dokumentation. Es spricht jedoch nichts dagegen, die nachfolgend
empfohlenen Methoden auf die Interne Technische Dokumentation anzuwen-
den.
Es wird ein Ablauf nach Bild 6 empfohlen, der systematisch von der Zusam-
menstellung der notwendigen Informationen für eine Dokumentation hin zum
Erstellungsprozess mit Texten und Visualisierungsmitteln führt.

5.1 Strukturieren
Strukturieren: Informations- Um die Auswahl der Dokumenttypen zu definieren und für jedes Dokument
auswahl treffen, den Aufbau und die innere Gliederung festzulegen, sind folgende Eingangs-
Strukturkonzept definieren,
informationen wichtig:
Gliederung festlegen
• zutreffendes Normenwerk
• Qualitätsanforderungen

– 30 – VDI 4500 Blatt 4 / Part 4


Creation of documentation
Structuring

Text For text designing, the external, formal appearance, on the one hand, and the
content writing, on the other hand must be specified.

Content structuring is oriented to the purpose of the external technical docu-


mentation and, therefore, has its sights set on the product, on a task to be re-
solved or the sequence of learning steps of the user.

In case of sensitive nature of texts (e.g. safety instructions), special attention


must be paid to consistent formulation.
Image As important aids for comprehension, images in technical documentation
must be clear and explicit and must be limited to the essentials. They must in
any case support the text and must be logically integrated in the text according
to the sequence of actions.
Images are diagrams as well as pictograms, symbols, illustrations and photos.
The applicable set of standards, the purpose of information and the target
group primarily determine as to how any information shall be visualised.

In view of possibly necessary translations, images should not contain any


text.

4.3 Output medium


Of considerable importance is the timely selection of media for later distribu-
tion and use. The layout rules for the output media print, display screen and
multimedia vary and are, as a rule, not compatible with each other.

Thus, for output of text, it must be considered that reading speed in case of
hard copy documents is up to 30 % higher as compared to output on the mon-
itor. Furthermore, reading of hard copy is perceived as less strenuous, and the
reader can reproduce more from what he has read. The evaluation of reada-
bility of display screen texts is influenced more strongly by the motivation
and expectation of the user than in case of paper-based documents.
The development of a layout concept is especially demanding if the technical
documentation is meant for output in several media (cross-media publishing).

5 Creation of documentation
The contents of this section mainly refer to external technical documentation.
However, there is no reason why the methods recommended in the following
should not be applied to internal technical documentation.

Recommended is a sequence of actions according to Figure 6, which sys-


tematically leads from the compilation of the necessary information for doc-
umentation up to the creation process with text and visualisation means.

5.1 Structuring
Structuring: information In order to define the selection of document types and to specify the structure
selection, defining the and the internal arrangement for each document, the following input informa-
structural concept, specifying
tion is important:
the organisation and
arrangement • applicable set of standards
• quality requirements

VDI 4500 Blatt 4 / Part 4 – 31 –


Dokumentation erstellen
Output medium

Bild 6. Erstellen eines Dokuments – vom Strukturkonzept bis zur Erstellung

• Produktanalyse
• interne oder kundenspezifische Regelwerke
• Zielgruppenanalyse
• Art der Verteilung
• markt- und kundenspezifischen Erwartungshaltungen an die Dokumenta-
tion
Auf Basis dieser Eingangsinformationen ergibt sich nahezu zwangsläufig die
Definition von Dokumententypen sowie die Dokumentenstruktur der Einzel-
dokumente. Zum inneren Aufbau geben die einschlägigen Normen und EU-
Richtlinien mit Verweisen auf die Benutzerinformation wichtige Hinweise,
die unbedingt zu befolgen sind.
Die Vorgehensweise der Strukturierung lässt sich in folgende beispielhafte
Schritte gliedern:
a) gesammelte Informationen aus Recherchen, Analysen und Vorgaben be-
nennen
b) erforderliche und gewünschte Informationen für die Dokumentation aus-
wählen
c) Grobgliederung erstellen (Makrostruktur)
d) ausgewählte Informationen in Abschnitte ordnen (Mikrostruktur)
Eine so aufgebaute Dokumentenstruktur der Technischen Dokumentation
führt zielgerichtet zur sicheren und wirtschaftlichen Nutzung des Produkts.
Empfehlungen für den Informationen für unterschiedliche Zielgruppen sollten in getrennten Doku-
Zielgruppenbezug menten verfasst werden oder zumindest deutlich voneinander getrennt in
einem Dokument erscheinen.
Die Inhaltsstruktur kann nach unterschiedlichen Schwerpunkten aufgebaut
werden:
• produktorientiert
• vorschriftenorientiert
• zielgruppenorientiert
• aufgabenorientiert
• vermittlungsorientiert
In der Praxis ergeben sich häufig Mischformen.
Informationen für Fachpersonal sind deutlich zu kennzeichnen, um eine Aus-
führung durch Laien zu verhindern. Dazu ist die jeweilige Zielgruppe eindeu-
tig zu definieren.

– 32 – VDI 4500 Blatt 4 / Part 4


Creation of documentation
Structuring

Figure 6. Creation of a document – from the structural concept up to creation

• product analysis
• internal or customer-specific body of rules and regulations
• target group analysis
• type of distribution
• market and customer-specific expectations vis-à-vis the documentation

The definition of document types as well as the document structure of the in-
dividual documents almost inevitably follows from this input information. As
concerns the internal organisation and arrangement, the pertinent standards
and EU directives with references to user information give important instruc-
tions which absolutely must be followed.
The procedure of structuring can be classified into the following exemplary
steps:
a) naming the collected information from research, analysis and specifica-
tions
b) selecting the necessary and desired information for the documentation

c) creating a rough structuring (macrostructure)


d) arranging selected information in sections (microstructure)
Such a document structure of technical documentation leads purposefully to
safe and economical use of the product.
Recommendations for Information for different target groups should be composed in separate docu-
target group reference ments or should, at least, appear clearly separated from each other within a
document.
The content structure can be composed with different emphases:

• product-oriented
• rule-oriented
• target group oriented
• task-oriented
• communication-oriented
In practice, mixed types are frequently used.
Information for technical personnel is to be clearly marked, in order to pre-
vent execution by laymen. The respective target group is explicitly defined to
this end.

VDI 4500 Blatt 4 / Part 4 – 33 –


Dokumentation erstellen
Modularisieren

Werden Informationen für unterschiedliche Zielgruppen zusammengefasst,


ist vom niedrigsten Kenntnisstand und den höchsten Sicherheitserwartungen
auszugehen. Mindestqualifikationen und die Zielgruppen sind eindeutig an-
zugeben.
Inhalt Inhalt und Beschreibungstiefe der verschiedenen Dokumente ergeben sich
aus den Ergebnissen der vorangegangenen Analysen. Mindestangaben aus
den für das Produkt anzuwendenden Gesetzen, Vorschriften, Richtlinien und
Normen sind unbedingt zu beachten. Der Lieferumfang ist vollständig zu do-
kumentieren. Die Technische Dokumentation muss dem technischen Stand/
der Ausführung des Produkts entsprechen. Die Beschreibungstiefe orientiert
sich an der Erklärungsbedürftigkeit des Produkts und am After-Sales-Kon-
zept des Herstellers/Lieferanten.

5.2 Modularisieren
Aus folgenden Gründen sollte der modulare Aufbau einer Dokumentation im
Prozess verankert werden:
a) Die Modularisierung von Dokumentationsinhalten gemäß dem techni-
schen Aufbau des Produkts und den jeweils zuzuordnenden Nutzerinfor-
mationen vereinfacht den Entstehungsprozess der Dokumentation.
b) Ein baugruppen- oder komponentenbezogener Aufbau der Dokumentati-
onsinhalte begünstigt die Dokumentation von Produktvarianten.
c) Wiederholt nutzbare Inhalte, die in mehreren Dokumentenstrukturen ver-
wendet werden, reduzieren den Aufwand für das Erstellen, Lektorieren
und Pflegen der Dokumentation.
Es empfehlen sich folgende Abläufe:
a) Zerteilen („Granulieren“) der Gesamtdokumentation in zweckmäßige un-
abhängige Informationseinheiten (Module)
b) Prüfen der Module auf Konsistenz und Selbstständigkeit
c) Metadaten für die eineindeutige Identifizierung der Module vergeben
d) Bausteinverwaltung für das Zusammenstellen einer Gesamtdokumenta-
tion aus zentral verwalteten Modulen einrichten

Bild 7. Aufbau verschiedener Dokumente (hier: Einführung, Bedienung, Wartung) aus mehrfach ver-
wendbaren Modulen eines zentralen Bausteinpools, der auch unterschiedliche Produktvarianten bedie-
nen kann

Das Ergebnis eines solchen Ablaufs sind einzelne Informationsmodule mit


eindeutig zugeordneten Objekteigenschaften (Metadaten). Diese Module

– 34 – VDI 4500 Blatt 4 / Part 4


Creation of documentation
Modularising

If information for different target groups is summarised, the lowest level of


knowledge and highest expectations of safety must be presumed. Minimum
qualifications and the target groups must be explicitly specified.

Content Content and depth of description of the various documents result from the re-
sults of the preceding analyses. Minimum specifications from the laws, regu-
lations, guidelines and standards to be applied to the product absolutely must
be followed. The scope of delivery must be documented in full. The technical
documentation must correspond to the state of the art/the design of the prod-
uct. The depth of description is oriented to the need for explanation of the
product and to the after-sales concept of the manufacturer/supplier.

5.2 Modularising
The modular structure of documentation must be anchored in the process for
the following reasons:
a) The modularisation of documentation contents according to the technical
composition of the product and of the user information to be respectively
assigned simplifies the creation process of the documentation.
b) Assembly groups or component-based structure of the documentation
contents is beneficial for the documentation of product variants.
c) Contents that can be used repeatedly, which can be used in several docu-
ment structures, reduce the effort for the creation, proofreading and up-
dating of documentation.
The following sequences are recommended:
a) fragmentation (“granulation”) of the entire documentation into conven-
ient, independent information units (modules)
b) checking of the modules for consistency and independence
c) assignment of metadata for the unique identification of the modules
d) setting up of module management for the compilation of an overall docu-
mentation from centrally managed modules

Figure 7. Composition of various documents (here: introduction, service, maintenance) from multiple
use modules of a central module pool, which can serve even different product variants

The result of such a sequence of actions is the formation of individual infor-


mation modules with explicitly assigned object properties (metadata). These

VDI 4500 Blatt 4 / Part 4 – 35 –


Dokumentation erstellen
Standardisieren

können unabhängig voneinander – auch durch verschiedene Mitarbeiter – er-


stellt und lektoriert werden.
Empfehlungen • Das Modularisieren ist eine Grundvoraussetzung für die Bearbeitung
Technischer Dokumentationen in sogenannten Redaktionssystemen. Aber
auch für den Erstellungsprozess in herkömmlichen Textsystemen ist das
Verwalten kleiner unabhängiger Module wirtschaftlich und aus Sicht der
Qualitätssicherung von Vorteil.
• Die Festlegung der Modulgröße ist entscheidend für das wirtschaftliche
Arbeiten: Zu kleine Module beispielsweise erschweren die Verwaltung,
können aber für Übersetzungsprozesse kostengünstiger sein. Zu große
Module dagegen schränken die Mehrfachnutzung ein.
• Die Module müssen in sich geschlossen und konsistent sein, damit ihre
Kernaussagen vollständig sind. Andererseits sind redundante Inhalte uner-
wünscht.
• Ist der Gesamtinhalt des Moduls unverändert wiederverwendbar? Enthält
das Modul nur ein inhaltlich abgeschlossenes Thema?
• Ist das Modul für alle Medien geeignet?
• Sind die Texte medienneutral und frei von Bezügen zu anderen Modulen?
• Sind Abbildungen für alle Medien geeignet (Auflösung, Farbraum)?

5.3 Standardisieren
Die Standardisierungsziele in der Technischen Dokumentation dienen vor
allem der Transparenz der Dokumentationsprozesse, der Vereinfachung von
Abläufen, der Kompatibiliät von Schnittstellen aller Art und insgesamt der
Reduzierung von Kosten.
Standardisieren lassen sich:
• dokument- und produktbezogene Gliederungsstrukturen
• Visualisierungsmittel
• Sprache und deren Gebrauch
• Gestaltungsvorgaben
• Publikationsprozesse und Medien
• Datei- und Austauschformate
• Arbeitsorganisation
Redaktionshandbuch als In Style-Guides, Corporate-Design-Leitfäden, Qualitätsmanagement-Hand-
Hilfsmittel für konsistente büchern und Redaktionshandbüchern werden die unternehmensbezogenenen
Standardisierung
und produktbezogenen Standardisierungsziele und -mittel dokumentiert und
verbindlich vorgegeben.
Das Redaktionshandbuch definiert den gesamten Workflow im Dokumentati-
onsbereich und schreibt die Dokumentationsprozesse fest. Dazu gehören:
• Datenschnittstellen
• Softwareeinsatz, Technik- und Werkzeugeinsatz
• Dokumententypen und -medien
• Verantwortlichkeiten und Zuständigkeiten
• Prozessschnittstellen
• Freigabeprozesse
• Qualitätsmanagement
Obwohl das Redaktionshandbuch firmenspezifisches Know-how enthält und
daher nicht breit gestreut werden sollte, ist es sinnvoll und notwendig, allen
am Dokumentationsprozess beteiligten Stellen zumindest die einschlägigen

– 36 – VDI 4500 Blatt 4 / Part 4


Creation of documentation
Standardisation

modules can be created and proof-read independent of each other – even by


different colleagues.
Recommendations • Modularisation is a basic prerequisite for the processing of technical doc-
umentation in so-called content management systems. Even for the crea-
tion process in conventional word processing systems, the management of
smaller, independent modules is economical and advantageous from the
aspect of quality assurance.
• The specification of the module size is decisive for working economi-
cally: Too small modules, for instance, complicate the management,
though they can be more economical for translation processes. Too large
modules, on the other hand, restrict multiple uses.
• The modules must be self-contained and consistent in order that their
quintessence is complete. On the other hand, redundant contents are unde-
sired.
• Is the overall content of the module reusable unchanged? Does the module
contain only one topic and, that too, self-contained in terms of content?
• Is the module suitable for all media?
• Are the texts media-neutral and free of references to other modules?
• Are the illustrations suitable for all media (resolution, colour space)?

5.3 Standardisation
The standardisation objectives in technical documentation primarily serve the
purpose of transparency of documentation processes, the simplification of
process flows, the compatibility of interfaces of all kinds and the overall re-
duction of costs.
Standardised can be:
• document-based and product-based structuring
• visualisation means
• language and its use
• layout specifications
• publication processes and media
• file and exchange formats
• work organisation
Editorial manual as aid for In style guides, corporate design guidelines, quality management manuals
consistent standardisation and editorial manuals, the company-based and product-based standardisation
goals and means are documented and bindingly specified.

The editorial manual defines the overall workflow in the documentation area
and establishes the documentation processes. These include:
• data interfaces
• software deployment, deployment of technology and tools
• document types and document media
• responsibilities and competencies
• process interfaces
• approval processes
• quality management
Although the editorial manual contains company-specific know-how and
therefore should not be widely distributed, it is advisable and necessary to for-
ward at least the pertinent chapters to all the offices involved in the documen-

VDI 4500 Blatt 4 / Part 4 – 37 –


Dokumentation erstellen
Erstellen

Kapitel weiterzugeben. Das betrifft auch Dienstleister wie freie Technische


Redakteure oder Übersetzer.

5.4 Erstellen
Dieser Abschnitt befasst sich hauptsächlich mit der Umsetzung der struktu-
rierten, modularisierten und standardisierten Inhalte in die verschiedenen
Dokumentenarten. Dem Texten kommt dabei die größte Bedeutung zu, denn im
Bereich der Technischen Dokumentation sind andere Kommunikationswege
– beispielsweise textlose Bildanleitungen – vergleichsweise wenig verbreitet.
Zu unterscheiden sind verschiedene Textarten für unterschiedlichen Medien-
einsatz: So gelten besondere Regeln für gesprochenen Text in Multimedia-
Anleitungen oder übersetzungsfreundliche Texte in Printanleitungen.
Zielgruppengerecht In jedem Fall aber gelten für den Verfasser Technischer Dokumentation be-
formulieren sondere Regeln, die sich nicht notwendigerweise an den in der Schule gelern-
ten Qualitätsbegriffen orientieren. Die Texte müssen ausschließlich in einer
zielgruppengerechten Sprache ausgeführt sein, deren einziges Ziel es ist,
technisch komplexe Sachverhalte prägnant, eindeutig und verständlich zu
vermitteln. Das Resultat muss eine Verkürzung der Lesezeit und eine nach-
haltige Erinnerung sein.
In der Technischen Dokumentation sind Wortwiederholungen kein Zeichen
für schlechtes Deutsch, sondern im Gegenteil erwünscht, um eindeutiges Ver-
ständnis beim Anwender sicher zu erreichen. Eine einfache Sprache ist auch
deswegen gefordert, weil damit die Eindeutigkeit der Ausgangssprache für
den Übersetzungsprozess erzielt wird.
Sprachen Natürliche Sprachen werden als von Menschen gesprochene Sprachen be-
schrieben, die historisch gewachsen sind, wie Deutsch, Englisch, Französisch
usw. Sie enthalten neben einer Vielzahl von Regeln nahezu unzählige Aus-
nahmen und Uneindeutigkeiten. Trotzdem kommt keine Darstellungsart in
der Technischen Dokumentation ohne natürliche Sprache aus.
Künstliche Sprachen wurden für ganz bestimmte Zwecke neu konstruiert, oft
von nur einigen Personen oder einer Gruppe. Zwei der bekanntesten Katego-
rien dieser Sprachen sind:
• Plansprachen, um die internationale Verständigung zwischen verschiede-
nen Kulturen zu erleichtern, beispielsweise Esperanto
• Formale Sprachen, deren praktische Anwendung vor allem im Bereich der
Logik und der Informatik bzw. Programmierung liegt. Die bekanntesten
formalen Sprachen sind C++, Java, SQL, HTML, XML, UML usw.
Formulierungen in Nutzerinformationen sind haftungsbegründend, wenn sie
nicht auf die durchschnittlichen Kenntnisse und Erfahrungen der Zielgruppe
Grundregeln für angemessen ausgerichtet und deshalb für diese nicht unmittelbar verständlich
verständliche Texte sind. Einige Grundregeln führen zu verständlichen und eindeutig zu überset-
zenden Texten:
• kurze Sätze, einfacher Satzaufbau
• Fachbegriffe sind beim ersten Vorkommen oder in einem Glossar zu er-
läutern. Das Erfinden von Fachbegriffen sollte vermieden werden.
• Fachjargon ist unbedingt zu vermeiden. Es empfiehlt sich, während des
Verfassens bereits eine Terminologie zu erarbeiten, die die einheitliche
Verwendung von Begriffen, Wendungen usw. sicherstellt. Dabei sollten
nicht nur technische Fachbegriffe betrachtet werden. Auch Begriffe/Wör-
ter/Wendungen, die z.B. für Handlungsanweisungen verwendet werden,
sollten einheitlich sein.

– 38 – VDI 4500 Blatt 4 / Part 4


Creation of documentation
Creation

tation process. This equally includes service providers such as self-employed


technical writers or translators.

5.4 Creation
This section deals mainly with the conversion of the structured, modularised
and standardised contents into the various document types. In the process,
content writing is accorded the highest importance, since other communica-
tion channels – for example textless pictorial instructions – are comparatively
less widespread in the area of technical documentation.
To be distinguished are various text types for diverse media use: Thus, special
rules apply for spoken text in multimedia instructions or translation-friendly
texts in print instructions.
Target group oriented In any case, however, the composer of technical documentation is subject to
formulation special rules which are not necessarily oriented to the quality terms learnt in
school. The texts must be exclusively embodied in a target group oriented lan-
guage, the single goal of which is to communicate technically complex facts
concisely, explicitly and comprehensibly. The result must be shortening of
reading time and lasting recall.

In technical documentation, repetition of words is not a sign of poor language


skills; on the contrary, it is desired, in order to ensure that the user under-
stands the word unambiguously. Simple language is also required because the
unambiguity of the source language is therewith achieved for the translation
process.
Languages Natural languages are described as languages spoken by man, which have
evolved historically, such as German, English, French, etc. In addition to a va-
riety of rules, they contain innumerable exceptions and ambiguities. Neverthe-
less, no notation in technical documentation can do without natural language.

Artificial languages were reconstructed for very specific purposes, often only
by a few persons or a group. Two of the best known categories of these lan-
guages are:
• constructed languages, in order to simplify international comprehension
between various cultures, for example Esperanto
• Formal languages, the practical application of which lies primarily in the
area of logic and information technology and/or programming. The best
known formal languages are C++, Java, SQL, HTML, XML, UML, etc.
Formulations in user information are grounds for liability, if they are not ad-
equately adapted to the average level of knowledge and experiences of the tar-
Basic rules for get group and are therefore not directly comprehensible for these users. A few
comprehensible texts basic rules result in comprehensible and unambiguously translatable texts:

• short sentences, simple sentence structure


• Technical terms are to be explained when they first appear or in a glossary.
Invention of technical terms should be avoided.
• Technical jargon absolutely must be avoided. It is recommended to de-
velop a terminology at the time of composing the text, so that uniform use
of terms, phrases, etc. is ensured. Terminology should not consider techni-
cal terms alone. Even terms/words/phrases, which are, for instance, used
for describing actions, should be uniform.

VDI 4500 Blatt 4 / Part 4 – 39 –


Dokumentation erstellen
Erstellen

Ergebnisse anwendungsspezifischer Produktbeobachtungen über angemes-


sen lange Zeiträume liefern den Maßstab für die Notwendigkeit des Einsatzes
von Warnhinweisen und Definitionen von bestimmungswidrigem Gebrauch
oder Missbrauch.
Regionale oder technische (Anwendungs-)Besonderheiten (z.B. für die An-
wendung in den USA oder in Schwellen-/Entwicklungsländern) sind zu be-
rücksichtigen, damit die Handlungsergebnisse von kulturellen Unterschieden
unbeeinflusst überall zum selben Ergebnis führen. Gezielte Einzelhinweise
sind zusätzlich an den Stellen zu wiederholen, an denen Ursachen oder Mög-
lichkeiten für gefährlichen Miss- oder Fehlgebrauch entstehen können.
Übersetzung Übersetzung ist die möglichst genaue Übertragung eines Texts in eine Fremd-
sprache, das heißt, bei einer Rückübersetzung muss das Ergebnis weitgehend
dem ursprünglichen Text entsprechen.
Um dies sicherzustellen, ist auf eine übersetzungsgerechte Formulierung des
Ausgangstexts zu achten.
Zweckmäßig ist es,
• eine einheitliche Terminologie in den verschiedenen Fremdsprachen festzu-
legen und mit dem Übersetzer die Einhaltung verbindlich zu vereinbaren,
• die elektronischen Formate von Quelltext und Zieldokument sowie die zu-
gelassenen Übersetzungswerkzeuge vorzuschreiben,
• Prüfroutinen für die Übersetzungen vorzusehen,
• für die Abwicklung von Übersetzungsaufträgen die Vorgaben der ein-
schlägigen Normen zu vereinbaren.
Grundsätzlich sollten fremdsprachige Technische Dokumentationen durch
fachkundige Mitarbeiter im Verwenderland/Einsatzland geprüft werden.
Lokalisierung Bei Übersetzungen sind grundsätzlich Bräuche und Gewohnheiten sowie der
normale Ausbildungsstand im Zielland zu berücksichtigen. Dabei wird es zu-
meist notwendig werden, dass der Übersetzer Formulierungen anpasst. Seine
Freiheitsgrade dabei sind vertraglich und haftungsrechtlich zu klären.

Jedoch kann auch der Technische Redakteur die Übersetzung durch Anpassen
der Inhalte vorbereiten. Das betrifft vor allem auch lokale Normen, Richt-
linien und Gesetze, die eine geänderte Technische Dokumentation in jedem
Zielland erfordern können. Dieser Prozess nennt sich Lokalisierung und ist in
der Regel gegenüber einer reinen Übersetzung zwingend erforderlich.
Visualisieren Mithilfe der Visualisierung werden Sachverhalte in die Form einer grafischen
oder visuellen Veranschaulichung gebracht (Bild oder Bildfolge).
Bei Technischen Dokumentationen, die abstrakte Daten und komplexe Zu-
sammenhänge beschreiben, die sprachlich oder logisch nur schwer zu formu-
lieren sind, ist es geboten, die sprachlichen Inhalte durch Visualisierungen zu
ergänzen und sie damit besser verständlich zu machen.
Ein größerer Bildanteil erhöht die Verständlichkeit und die Attraktivität und
verbessert zudem den Leseanreiz.
Von Fall zu Fall ist abzuwägen, welche Art der visuellen Umsetzung optimal
geeignet ist. Hier sind sorgfältig die Erkenntnisse der Wahrnehmungsfor-
schung und die Entwicklung der technischen Möglichkeiten der Visualisie-
rungsmittel zu beobachten. Manche bewährten Methoden zur Erstellung von
Visualisierungselementen werden durch neue wirtschaftlichere Methoden er-
setzt. So lassen sich beispielsweise aufwendig zu erstellende Dokumentati-
onsfotos durch fotorealistische Computergrafik ersetzen, die unmittelbar mit
entsprechenden Programmen aus den häufig im Konstruktionsbereich einge-

– 40 – VDI 4500 Blatt 4 / Part 4


Creation of documentation
Creation

Results of use-oriented product monitoring over adequately long periods de-


liver the yardstick for the necessity of the use of warning notes and definitions
of use contrary to the intended purpose or misuse.

Regional or technical (application) specifics (e.g. for use in the USA or in


threshold/developing countries) must be considered, so that the results of the
actions are the same everywhere irrespective of the influence of cultural dif-
ferences. Selective individual notes must be additionally repeated at places,
where there might be cause for or the potential of hazardous misuse or incor-
rect use.
Translation Translation is a faithful and accurate transfer of a text into a foreign language,
as far as possible, i.e. the result of a back translation must correspond to the
source text, as far as possible.
To ensure this, care must be taken that formulation of the source text is trans-
lation-friendly.
Advisable is
• to specify standardised terminology in the various foreign languages and
to make it binding upon the translator to adhere to the terminology,
• to prescribe the electronic formats of source text and target document as
well as the permitted translation tools,
• to foresee checking routines for the translations,
• to agree upon the specifications of the pertinent standards for the handling
of translation assignments.
In principle, foreign-language technical documentation should be checked by
specialist employees in the country of use.
Localisation During translation, customs and habits as well as the normal education level
in the target country must be considered, in principle. In the process, it be-
comes mostly necessary that the translator adapts formulations to the local
conditions. At the same time, his degree of freedom must be clarified contrac-
tually and in terms of liability law.
However, the technical writer can also prepare the translation by adapting the
contents accordingly. This concerns primarily local standards, guidelines and
laws, which can make changed technical documentation in each target coun-
try necessary. This process is called localisation and is, as a rule, absolutely
necessary as compared to a mere translation.
Visualisation With the help of visualisation, facts are transformed into a graphic or visual il-
lustration (picture or series of pictures).
In technical documentation, which describes abstract data and complex con-
texts, which are difficult to formulate linguistically or logically, it is impera-
tive to add visualisation to the linguistic content and to therewith make them
better understandable.
A relatively large proportion of pictures increases comprehension and the at-
tractiveness and furthermore improves reading pleasure.
It must be weighed on a case-by-case basis as to which type of visual imple-
mentation is optimally suitable. At this juncture, the findings of the cognitive
research and the development of technical options of visualisation means
must be carefully observed. Some proven methods for the creation of visual-
isation elements are being replaced by newer, more economical methods.
Thus, for instance, the laborious process of documentation photos can be re-
placed by photorealistic computer graphics, which can be directly created
with the appropriate programmes with 3-D-CAD data frequently used in the

VDI 4500 Blatt 4 / Part 4 – 41 –


Dokumentation erstellen
Endfassung

setzten 3-D-CAD-Daten entsteht – und das mit vergleichsweise geringem


Aufwand.
Bedeutung von Farben Bei der Verwendung von Farben ist auf die unterschiedliche Bedeutung von
Farben in den verschiedenen Kulturkreisen zu achten.

5.5 Endfassung
Während des Erstellungsprozesses und danach sind verschiedene Anforde-
rungen zu beachten, die nichts mit den Inhalten der Dokumente zu tun haben,
sondern die Bestandteil des Ausführungskonzepts sind.

5.5.1 Lebensdauer der Dokumentation spezifizieren


Eine wesentliche Aufgabe bei der Dokumentationsplanung ist die Spezifika-
tion der Lebensdauer aller Dokumente, die für den Nachweis der Sorgfalts-
pflicht des Herstellers gefordert sind, und der Externen Technischen Doku-
mentation. Die notwendigerweise zu überschreitende Lebensdauer liegt bei
Konsumgütern im Bereich weniger Jahre bis Jahrzehnte, bei langlebigen In-
vestitionsgütern bis zur Beendigung des Produktlebenszyklus teilweise über
100 Jahre.
Danach richtet sich die Auswahl von Betriebssystemen und Anwendersoft-
ware sowie von Formaten und Datenträgern für die Langzeitarchivierung. Bei
den kurzen Lebenszyklen im EDV-Bereich kann eine Planung über einen
Zeitraum von mehr als zehn Jahren kaum zuverlässig erfolgen. In jedem Fall
sind bei derartigen Zeiträumen sorgfältig ausgeführte Dokumentationen der
Softwarebedienung, der Dateiablagen und der Dokumentenzusammenstel-
lung unabdinglich.
Dokumentationssoftware Merke: Ein von der Investition her scheinbar preisgünstiges Dokumentati-
onskonzept kann hohe Folgekosten und Aufwendungen beim täglichen Um-
gang nach sich ziehen.

5.5.2 Einheitliche und herstellerunabhängige Dateiformate für


langfristige Lesbarkeit
Nach Auslieferung der Technischen Dokumentation an den Kunden müssen
die Ausgangsdaten, Quelldokumente und Freigabeversionen sowie die In-
terne Technische Dokumentation zum späteren Nachweis der Erfüllung der
Sorgfaltspflichten des Herstellers archiviert werden. Die Aufbewahrungsfris-
ten können – abhängig von der Länge des Produktlebenszyklus – mehr als ein
Jahrhundert betragen, wenn man langlebige Investitionsgüter betrachtet.
Entscheidend für die Langlebigkeit und Reproduzierbarkeit der archivierten
Datenbestände ist die Sorgfalt bei der Auswahl der geeigneten Methoden:
• Verwenden einheitlicher und herstellerunabhängiger Datenaustauschfor-
mate mit dem Ziel der langfristigen Lesbarkeit, der Austauschbarkeit von
Informationen, der Übertragbarkeit auf unterschiedliche Betriebssysteme,
der drucktechnischen Verarbeitung und der Verteilung von technischen
Dokumenten in elektronischer Form. Eine Empfehlung für die Weitergabe
druckfertiger Dokumente stellt das ursprünglich von Adobe entwickelte
Format PDF in seiner Ausprägung PDF/A (A für Archivierung) dar, das
aus jeder Dokumentationssoftware abgeleitet werden kann und das darü-
ber hinaus auch die notwendigen Sicherheits- und Schutzmechanismen
gegenüber unbefugten Änderungen an freigegebenen Dokumenten bietet.
PDF-Generatoren sind inzwischen von vielen Anbietern erhältlich. Mit
den Formaten „Mars“ (Adobe®) und „XPS“ (Microsoft®) stehen zukünf-
tig Alternativen bereit.

– 42 – VDI 4500 Blatt 4 / Part 4


Creation of documentation
Final version

construction sector – and, that too, with comparably less effort and expendi-
ture.
Significance of colours While using colours, the difference in importance and meaning attached to
colours in various cultures must be borne in mind.

5.5 Final version


During the creation process and thereafter, various requirements must be
borne in mind, which have nothing to do with the contents of the documents,
but are a component of the design concept.

5.5.1 Specifying the lifetime of the documentation


An essential task during documentation planning is to specify the lifetime of
all documents, which are required for proof of due diligence of the manufac-
turer and of the external technical documentation. The lifetime that must nec-
essarily be exceeded is in the range of a few years to decades in case of con-
sumer goods, and up to end of the product lifecycle, at times over hundred
years, in case of long-lasting capital goods.

This is the basis for the selection of operating systems and application soft-
ware as well as formats and data carriers for long-time archiving. In case of
short lifetimes in the EDP area, planning over a period of more than ten years
can hardly be reliable. In any case, carefully designed documentation of soft-
ware operation, file storage and document compilation is indispensible for
such periods.

Documentation software Note: An apparently lowest priced documentation concept from the point of
view of investment can entail high consequential costs and expenditures in the
course of daily handling.

5.5.2 Uniform and manufacturer-independent file formats for


long-term readability
After the delivery of the technical documentation to the customer, the source
data, source documents and release versions as well as the internal technical
documentation must be archived for later proof of fulfilment of due diligence
of the manufacturer. The compulsory periods for retention – depending upon
the length of the product lifecycle – can be more than one century, if one con-
siders long-lasting capital goods.
Decisive for the long lifecycle and reproducibility of the archived databases is
the care taken during the selection of the appropriate methods:
• Use of uniform and manufacture-independent data exchange formats with
the aim of long-term readability, exchangeability of information, transfer-
ability to various operating systems, processing for printing and the distri-
bution of technical documents in electronic form. A recommendation for
the transmission of print-ready documents is represented by the format
PDF originally developed by Adobe in its PDF/A feature (A for archiv-
ing), which can be derived from every documentation software and that
furthermore offers the necessary safety and protection mechanisms
against unauthorised changes to released documents. PDF generators can
meanwhile be obtained from several vendors. With the formats “Mars”
(Adobe®) and “XPS” (Microsoft®), alternatives will be available in future.

VDI 4500 Blatt 4 / Part 4 – 43 –


Dokumentation erstellen
Dokumentation anpassen

• Verwenden herstellerunabhängiger Dokumentenstandards konform zu den


Regelwerken XML oder SGML als gemeinsame Basis offener und unter-
schiedlicher Publishing-Systeme. Dadurch können einmal festgelegte Do-
kumentengerüste von unabhängig arbeitenden Dokumentationsteams mit
Inhalten ausgefüllt werden. Für die Publikation in unterschiedlichen Me-
dien sind zu den Grunddaten entsprechende Verarbeitungswerkzeuge nö-
tig, damit aus den Grunddaten z.B. HTML, PDF oder andere Formate er-
zeugt werden können. Für den Austausch der XML- oder SGML-Daten
zwischen verschiedenen Applikationen müssen entsprechende Schnittstel-
lenkonverter bereitgestellt werden, die die verschiedenen Dokumentstruk-
turen und Layoutvorgaben vom Quell- zum Zielprogramm überführen.
• Beim Festlegen der Datenaustauschformate muss die Definition langlebi-
ger Datenträger und Übertragungsmedien für eine spätere Verteilung (glo-
bale Netze, CD-ROM, interne Netzwerke ...) berücksichtigt werden.
• Für die technologieunabhängige Langzeitarchivierung empfehlen sich da-
gegen die Nachfolgeverfahren der Mikroverfilmung, die selbst als bislang
einzige Technologie den Nachweis einer Lesbarkeit über Zeiträume von
mehr als 50 Jahren erbringen konnte. Bei entsprechender Lagerung lässt
sich die Lesbarkeit von hochaufgelösten Mikrofilmen auf 500 Jahre aus-
dehnen. Mit entsprechenden künftigen Redigitalisierungsmethoden kön-
nen die Dokumente wieder in elektronische Strukturen konvertiert wer-
den.
Mikrofilmarchive bleiben sehr lange lesbar; man benötigt dazu nur ein
Mikroskop – ein Gerät auf sehr niedriger Integrationsstufe, von dem man
ausgehen kann, dass es auch in ferner Zukunft verfügbar sein wird. Zu-
dem können bei geeigneter Wahl des Mediums (neue Entwicklungen ver-
wenden wenig korrodierende Metallsubstrate) die Daten theoretisch über
Jahrtausende reproduzierbar aufbewahrt bleiben.

5.5.3 Versionskontrolle
Um Dokumente in unterschiedlichen Ausführungen eindeutig identifizieren
zu können, sollten unterschiedliche Stände der Dokumentation versioniert
werden. Hierdurch ist es möglich, einem Gerät in einem bestimmten Bauzu-
stand die passende Technische Dokumentation zuzuordnen und Änderungen
im Rahmen des Pflegeaufwands nachzuvollziehen. Bei Fehlern in überarbei-
teten Dokumenten kann auf einen früheren Zustand zurückgegriffen werden.
Ältere Versionen sollten archiviert werden, damit jederzeit auf alle ausgelie-
ferten Versionen zugegriffen werden kann. Insbesondere beim Einsatz von
Redaktionssystemen ist großes Augenmerk auf diese Forderung zu legen, da
nicht alle Redaktionssysteme diese Funktion umfassend bieten.

5.5.4 Auslieferung
Jede Technische Dokumentation ist ein Teil des Produkts und muss nach den
gesetzlichen Regeln mit diesem zum gleichen Zeitpunkt ausgeliefert werden.
Alle Tätigkeiten zum Erarbeiten, Prüfen und Fertigstellen der Technischen
Dokumentation sollten deshalb so rechtzeitig gleichlaufend mit den Entwick-
lungsarbeiten begonnen und organisiert werden, dass ausreichend freigege-
bene Technische Dokumentationen mit der Auslieferung der ersten Produkte
verfügbar sind.

5.6 Dokumentation anpassen


Nachträglich angepasste oder nachträglich erstellte Dokumentation für ein
bereits existierendes Produkt ist notwendig, wenn die Dokumentation mit
dem Produkt nicht übereinstimmt oder nicht vorhanden ist.

– 44 – VDI 4500 Blatt 4 / Part 4


Creation of documentation
Adapting of documentation

• Use of manufacturer-independent document standards conform to the set


of rules XML or SGML as common basis for open and different publish-
ing systems. Once specified document frameworks can thereby be filled in
with contents by independently working documentation teams. For publi-
cation in various media, the appropriate processing tools are needed in ad-
dition to the basic data, in order that e.g. HTML, PDF or other formats
can be generated from the basic data. For the exchange of XML or SGML
data between different applications, appropriate interface converters must
be provided, which transfer the various document structures and layout
specifications from the source to the target programme.

• While specifying the data exchange formats, the definition of long-lasting


data carriers and transfer media must be considered for a later distribution
(global networks, CD-ROM, internal networks ...).
• For technology-independent long-term archiving, on the other hand, the
follow-up process of microfilming is recommended, which is currently
the only technology which can furnish proof of readability over periods of
more than 50 years. With appropriate storage, the readability of high-reso-
lution microfilms can be extended to 500 years. With appropriate, future
redigitalisation methods, the documents can once again be converted into
electronic structures.

Microfilm archives are legible over long periods; all one needs is a micro-
scope – a device at a very low level of integration, about which it can be
assumed that it will remain available in the distant future as well. Addi-
tionally, the data can theoretically remain preserved in reproducible state
over thousands of years if the suitable medium is selected (new develop-
ments use less corrosive metal substrates).

5.5.3 Version control


To be able to explicitly identify documents in various versions, various sta-
tuses of documentation should be subjected to version control. Through this,
it is possible to assign the suitable technical documentation to a device in a
certain state of construction and to reconstruct changes made in the course of
updating of documents. In case of errors in revised documents, one can fall
back on an earlier status of documentation.
Older versions should be archived, so that all delivered versions can be ac-
cessed at any time. In particular while using content management systems,
special emphasis must be laid on this requirement, since not all content man-
agement systems offer this function comprehensively.

5.5.4 Delivery
Each piece of technical documentation is a part of the product and must be de-
livered simultaneously with the product according to statutory regulations.
All activities concerning developing, checking and finalisation of the techni-
cal documentation must therefore be begun and organised synchronously and
concurrent with the development work, such that sufficient approved techni-
cal documentation is available with the initial deliveries of the product.

5.6 Adapting of documentation


Subsequently adapted or subsequently created documentation for an already
existent product is necessary, if the documentation does not correspond to the
product or does not exist.

VDI 4500 Blatt 4 / Part 4 – 45 –


Qualitätsmanagement
Dokumentation anpassen

Dokumentation eines Im Rahmen der Inbetriebnahme kann es in der Praxis zu Änderungen des Pro-
definierten Zustands dukts kommen.
Dies können beispielsweise sein:
• Anpassungen der Software und der Steuerung,
• bauseitige Änderungen oder auch
• prozesstechnische Anpassungen.
Aus den genannten Gründen resultieren Änderungen der Dokumentation. Der
damit erreichte Stand der Dokumentation wird „As built“-Dokumentation
genannt. Sie bildet den tatsächlichen Zustand des Produkts zu einem im Ver-
trag definierten Zeitpunkt ab.
Dokumentation nach Umbau Die Dokumentation nach Umbau und Modernisierung entsteht meist im Be-
und Modernisierung reich Maschinen- und Anlagenbau. Falls das Produkt wesentlich verändert
wurde oder keine oder nur eine unzulängliche Dokumentation vorhanden ist,
ist es notwendig, diese Dokumentation zu erstellen oder zu aktualisieren. Die
Dokumentation muss den Zustand nach Abschluss der Maßnahmen wider-
spiegeln. Nur auf diese Weise ist eine weitere sichere technische und wirt-
schaftliche Nutzung möglich.
Nachdokumentation im Bereich Nachdokumentation, die im Bereich der Entwicklung von Software und Steu-
Software und Steuerung erung entsteht, wird meist Reverse-Dokumentation genannt. Der Code der
Software oder die Pläne der Steuerung werden in manchen Fällen während
der Entwicklung nicht, unvollständig oder unverständlich dokumentiert.

Dann ist es notwendig, den Code nachträglich zu dokumentieren oder so zu


aktualisieren, dass der tatsächliche Zustand widergespiegelt wird. Oft ist nur
auf diese Weise eine weitere technische und wirtschaftliche Nutzung, War-
tung und Weiterentwicklung möglich.

6 Qualitätsmanagement
Wie jedes andere Produkt soll auch die Technische Dokumentation eine be-
stimmte Qualität aufweisen, die durch systematische Prüfung der Einhaltung
von definierten Prozessabläufen erreicht wird. Zugleich ist auch die Wirk-
samkeit dieser Prozesse zu prüfen. Wie bei jedem anderen Produkt setzen die
Qualitätsprozesse bereits in der Konzeptionsphase einer Technischen Doku-
mentation ein und begleiten sie bis zum Ende des Produktlebenszyklus.
Begriffe Über das Qualitätsmanagement werden die Verfahren zum Nachweis der ge-
wünschten Dokumentationsqualität festgelegt. Zu den Verfahren gehören un-
ter anderem:
• Definieren der zu betrachtenden Qualitätskriterien und der zu erreichen-
den Qualität
• Auswahl der Ressourcen, z.B. Software
• Sicherstellen der Personalqualifikation
• Festlegen der Qualität bestimmender Prozessschritte
• Festlegen von Zuständigkeiten und Verantwortlichkeiten
• Definition von Prozessen zur Kosten- und Terminkontrolle
• Dokumentation festgestellter Mängel und Prozesse als Grundlage zur Be-
seitigung der Mängel
Die Qualitätssicherung sorgt im Planungs- und Erstellungsprozess einer
Technischen Dokumentation für die Einhaltung der vom Qualitätsmanage-

– 46 – VDI 4500 Blatt 4 / Part 4


Quality management
Adapting of documentation

Documentation of a In the course of commissioning, changes can be made to the product in prac-
defined condition tice.
These can, for example, be:
• adjustments of the software and of the control system,
• changes made at the customer end, or even
• process engineering adjustments.
Changes in documentation are made for the aforementioned reasons. The sta-
tus of documentation therewith achieved is called “as built” documentation.
It reflects the actual status of the product at a moment defined in the contract.

Documentation after rebuild Documentation after reconstruction and modernisation is created mostly in
and modernisation the area of mechanical and plant engineering. In case the product has been
changed significantly or if only inadequate documentation is available or
none at all, it is necessary to create or update this documentation. The docu-
mentation must reflect the status after conclusion of the measures. Only in
this way is continued safe, technical and economical usage possible.

Post-documentation in the area Post-documentation that is created in the area of development of software and
of software and control system control systems, if often referred to as reverse documentation. The code of the
software or the diagrams of the control system are in many cases not docu-
mented, incompletely documented or incomprehensibly documented during
the development phase.
Then it is necessary to document the code at a later date, or to update it such
that the actual status is reflected. Often, continued technical and economical
use, maintenance and further development are possible only in this way.

6 Quality management
Like every other product, technical documentation too must exhibit a certain
quality, which is achieved by systematic checking of the compliance with de-
fined process flows. Also, the effectiveness of these processes must be
checked. Like in every other product, the quality processes begin right at the
conception stage of technical documentation and accompany it up to the end
of the product lifecycle.
Terms Quality management is used to specify the processes that serve as proof of the
desired document quality. The processes include, among others:

• defining of the quality criteria to be regarded and the quality to be


achieved
• selection of the resources, e.g. software
• ensuring that the personnel are adequately qualified
• defining the quality of decisive process steps
• specification of responsibilities and competencies
• definition of processes for cost control and scheduling control
• documentation of identified defects and processes as the basis for the
elimination of defects
In the planning and creation process of technical documentation, quality as-
surance ensures that the processes defined by quality management are fol-

VDI 4500 Blatt 4 / Part 4 – 47 –


Qualitätsmanagement
Schwachstellenanalyse

ment festgelegten Verfahren. Dazu sind unter anderem folgende Verfahren


denkbar:
• manuelle oder automatische Prüfprozesse zum Abschluss bestimmter Do-
kumentationsschritte nach festgelegten Prüfkritierien
• regelmäßige Schulung von Mitarbeitern und Einweisung neuer Mitarbei-
ter
• Überprüfen der Dokumentation in Anwendertests und/oder durch Prüf-
prozesse
• Auswerten von Anwenderbewertungen
• Audits zur Überprüfung der Qualitätssicherungsprozesse und deren Ein-
haltung im täglichen Betrieb
Das Qualitätsmanagement des Dokumentationsprozesses ist einzubinden in
das übergeordnete Qualitätsmanagement des Unternehmens. Analog dazu
muss sichergestellt sein, dass alle dokumentationsrelevanten Prozessschritte
beschrieben sind; dazu bietet sich ein Redaktionshandbuch an, das als Verfah-
rens- oder Arbeitsanweisung im Sinne des Qualitätsmanagements dient.
Nach allgemeinem Verständnis von Qualitätsmanagement reicht eine Quali-
tätsprüfung am Ende des Produktionsprozesses nicht aus und entspricht auch
nicht dem Stand der Technik, weil sich durch die fehlende Prozessrückkopp-
lung zu den Dokumentationsverfahren keine dauerhafte Verbesserung erzie-
len lässt und Fehlerursachen nicht systematisch abgestellt werden können.
Ziel ist die Fehlervermeidung anstelle der Fehlerkorrektur.
Dem Qualitätsmanagement in der Technischen Dokumentation sind nicht nur
die unmittelbar für die Dokumentation zuständigen Mitarbeiter untergeord-
net, sondern auch die logischen Schnittstellen zu benachbarten Abteilungen,
Zulieferunternehmen, Kunden und Dienstleistern.
Die nachfolgenden Abschnitte beziehen sich vorwiegend auf die Externe
Technische Dokumentation, die in Form von Betriebsanleitungen, Bedie-
nungsanleitungen oder auch Marketing- und Vertriebsunterlagen vorliegen
kann.

6.1 Schwachstellenanalyse
Soll eine vorhandene Technische Dokumentation weiter verwendet oder
überarbeitet werden, so ist eine Schwachstellenanalyse unter Auswertung der
bisherigen Erfahrungen und der Kundenreaktionen sowie auf Basis prakti-
scher Anwendung von Prüfkriterien empfehlenswert. Alle Erfahrungen aus
gezielter Produktbeobachtung – insbesondere auch bei Wettbewerbsproduk-
ten – sind dabei zu berücksichtigen.
Zudem sollte auch der Dokumentationsprozess selbst in regelmäßigen Ab-
ständen einer Schwachstellenanalyse unterzogen werden.

6.1.1 Prüfkriterien
Jede Technische Dokumentation sollte in allen Phasen der Entstehung nach
einer produktspezifischen, unternehmenseigenen und anwendungsbezogen
erstellten Kriterienliste überprüft werden. Eine vollständige und allgemein
gültige Kriterienliste für alle denkbaren Produkte kann nicht erstellt werden,
weil Qualitätsanforderungen, Prüfkriterien und Dokumentationsprozesse un-
ternehmensspezifisch sind. Die nachfolgend beispielhaft aufgeführten Prüf-
kriterien müssen produktspezifisch und anwendungsbezogen individuell er-
gänzt werden.

– 48 – VDI 4500 Blatt 4 / Part 4


Quality management
Weak point analysis

lowed. In this context, the following processes, among others, are thinkable:

• manual or automatic inspection processes for the conclusion of certain


documentation steps according to defined inspection criteria
• regular training of employees and induction of new employees

• inspection of the documentation in user tests and/or through inspection


processes
• assessment of user ratings
• audits for checking the quality assurance processes and compliance with
them in daily operation
The quality management of the documentation process must be integrated in
the superordinate quality management of the company. Analogous to this, it
must be ensured that all the documentation-relevant process steps are de-
scribed; an editorial manual is available to this end, which serves as proce-
dural or work instruction in terms of quality management.
According to the general understanding of quality management, a quality
control at the end of the production process is not sufficient and also does not
correspond to state of the art, since permanent improvement cannot be
achieved and causes of error cannot be removed systematically due to lack of
process feedback to the documentation processes. The aim is to avoid errors
rather than to correct errors.
Not only the employees directly responsible for the documentation, but also
the logical interfaces with neighbouring departments, sub-suppliers, custom-
ers and service providers are subordinate to the quality management in tech-
nical documentation.
The following sections refer predominantly to external technical documenta-
tion, which can exist in the form of operating instructions, user guides or even
marketing and distribution documents.

6.1 Weak point analysis


Should an existent piece of technical documentation be used further or re-
vised, a weak point analysis with evaluation of the previous experiences and
customer reactions as well as on the basis of practical application of test cri-
teria is recommended. All experiences from selective product monitoring – in
particular also in case of competitive products – must be considered in the
process.
Additionally, the documentation process itself should be subjected to a weak
point analysis at regular intervals.

6.1.1 Test criteria


Each piece of technical documentation should be checked in all phases of cre-
ation according to a criteria list that is product-specific, company-owned and
use-oriented. A complete and generally valid criteria list for all thinkable
products cannot be created, because quality requirements, test criteria and
documentation processes are company-specific. The exemplary test criteria
listed in the following must be individually amended such that they are prod-
uct-specific and use-oriented.

VDI 4500 Blatt 4 / Part 4 – 49 –


Qualitätsmanagement
Schwachstellenanalyse

6.1.2 Liste allgemein gültiger Prüfkriterien


Begriffe

Aufgabengerecht Konform zu den vorgegebenen Zielen.


Effektiv Das definierte Ziel wurde erreicht (oder nicht).
Effizient Gutes Verhältnis des vorgegebenen Ziels zum dafür benötigten Aufwand.
Qualitätsmerkmale Prüfziele, die auf der Basis von definierten Prüfkriterien zu validieren sind.
Sicherheitshinweise • Wurden die Sicherheitshinweise vor der Handlungsanleitung oder vor den
betreffenden beschreibenden Texten angeordnet?
• Beginnt die Technische Dokumentation mit einem Sicherheitskapitel mit
allgemeinen Warnhinweisen?
• Sind Sicherheitshinweise klar nach Gefahrenarten gegliedert, z.B. Gefahr,
Vorsicht, Achtung?
• Sind die Sicherheitshinweise im Sinne der vorgeschalteten Risikobewer-
tung ausreichend?
• Sind überflüssige Sicherheitshinweise eingebaut, die auf die definierte
Qualifikation der Zielgruppe nicht abgestimmt sind?
• Entspricht die innere Struktur der Sicherheitshinweise den üblichen Re-
geln, z.B. nach der SAFE-Methode?
Dokumentation identifizieren • Ist eine eindeutige und unverwechselbare Bezeichnung auf der Techni-
schen Dokumentation angebracht?
• Sind die erforderlichen Kontaktinformationen des Inverkehrbringers ver-
merkt?
• Sind Angaben über den genauen Zweck, über Autor, Erstellungs- bzw.
Veröffentlichungsdatum, Version enthalten?
• Sind unverwechselbare Angaben zu Gerät/Maschine (Typ, Maschinen-
nummer, Seriennummer (je nach gesetzlichen produktbezogenen Forde-
rungen)) enthalten?
Aktualität • Entspricht der Stand der Technischen Dokumentation dem Stand des Pro-
dukts?
• Wurde die Technische Dokumentation ganz oder in den notwendigen Tei-
len zu Transport, Installation und Inbetriebnahme gemeinsam mit dem
Produkt ausgeliefert?
Sprachliche Richtigkeit • Einhaltung der Grammatik, ohne Rechtschreibfehler
• kurze, präzise und eindeutige Beschreibung
• Ergebnis einer qualitativen Verständlichkeitsprüfung (z.B. nach Hambur-
ger Verständlichkeitsmodell)
• Wurden die Sprachregeln eingehalten?
• Sind Fachbegriffe definiert?
• Ist die Fachterminologie konsistent, wurde immer dieselbe Bezeichnung
für dieselbe Funktion oder Sache verwendet? Wurden mehrere Funktio-
nen und Sachen mit unterschiedlichen Begriffen benannt?
Sachliche Richtigkeit • Übereinstimmung des Geschriebenen mit der tatsächlichen Situation
• Entsprechen die Visualisierungselemente dem aktuellen Stand der Ma-
schine/dem Gerät?
Inhaltliche Vollständigkeit • Übereinstimmung beispielsweise der Kapitel in Verzeichnis mit den tat-
sächlichen Kapiteln
• Vorhandensein aller Visualisierungselemente, auf die im Text verwiesen
wird

– 50 – VDI 4500 Blatt 4 / Part 4


Quality management
Weak point analysis

6.1.2 List of generally valid test criteria


Terms

Task-friendly Consistent with the specified aims.


Effective The defined goal was achieved (or not).
Efficient Good ratio of specified goal to effort/expenditure required for it.
Quality features Test goals that are to be validated on the basis of defined test criteria.
Safety notes • Have the safety instructions arranged before the instructions for action or
before the concerned descriptive texts?
• Does the technical documentation begin with a safety chapter with gen-
eral warnings?
• Are safety notes clearly structured according to the danger types, e.g.
danger, caution, attention
• Are the safety notes sufficient in the sense of the preceding risk assess-
ment?
• Have superfluous safety notes been incorporated, which are not attuned to
the defined qualification of the target group?
• Does the inner structure of the safety instructions correspond to the cus-
tomary rules, e.g. are they in accordance with the SAFE method?
Identifying of documentation • Is the technical documentation marked with a unique and unambiguous
identification?
• Is the required contact information of the marketing authorisation holder
noted on the documents?
• Does the documentation contain information about the exact purpose,
about author, date of creation and/or publication, version?
• Is unmistakable information about device/machine (type, machine
number, serial number (depending upon the statutory product-based re-
quirements) contained in the documentation?
Up-to-dateness • Does the state of technical documentation correspond to the state of the
product?
• Has the technical documentation with respect to transport, installation and
commissioning been delivered together with the product completely or in
part?
Linguistic correctness • following of grammatical rules, without spelling mistakes
• short, precise and unambiguous description
• result of a qualitative comprehension test (e.g. according to the Hamburg
model of comprehension)
• Have the language rules been followed?
• Have technical terms been defined?
• Is the technical terminology consistent, has the same term been used each
time for the same function or thing? Have several functions and things
been defined with various terms?
Factual correctness • correspondence of the written word with the actual situation
• Do the visualisation elements correspond to the current state of the ma-
chine/device?
Completeness of content • for instance, correspondence of the chapters in the list of contents with the
actual chapters
• presence of all visualisation elements which are referred to in the text

VDI 4500 Blatt 4 / Part 4 – 51 –


Qualitätsmanagement
Schwachstellenanalyse

• Nennung eventueller Ausnahmen und Spezialfälle


• Nennung von Optionen, die gegebenenfalls nicht vorhanden sind oder
nachträglich hinzugefügt werden können
• Entspricht die Gliederung den gesetzlichen Anforderungen und normati-
ven Vorgaben?
Eindeutigkeit, Konsistenz, • Vereinheitlichung der Begrifflichkeiten und der Namensgebung. Hierfür
Widersprüche vorteilhaft ist ein Vorhandensein von Regeln, um diese Vereinheitlichung
erreichen und kontrollieren zu können (Terminologie-Vorgaben).
• Einheitlichkeit von Formulierungen, z.B. immer „Schraube eindrehen“,
nicht wechselweise „Schraube eindrehen“ oder „Schraube einschrauben“
oder „Schraube anziehen“
• Richtigkeit aller Links in den Texten, keine ungelösten Querverweise
Redundanzen • Vermeidung von Inhaltswiederholungen (Ausnahmen: Wortwiederholun-
gen und solche Inhaltswiederholungen, die ein unnötiges Suchen durch
den Anwender verhindern)
• Es sollte vermieden werden, zu häufig mit Verweisen zu arbeiten. Die
Notwendigkeit von häufigem Blättern im Dokument reduziert die Effizi-
enz beim Leser und unterbricht den Lesefluss.
Gebrauchstauglichkeit • für die vorgegebene Zielgruppe und innerhalb eines gegebenen Benut-
für die Zielgruppe zungskontexts ausgewogene Inhalte mit der dafür angemessenen Präzi-
sion
• angepasst an das vorausgesetzt vorhandene Wissen, an die Intelligenz und
den Benutzungskontext der Zielgruppe sowie angepasst an die einge-
schätzten soziokulturellen und psychologischen Eigenschaften der Ziel-
gruppe
• „Zufriedenstellend“: Der Anwender verspürt die emotionale Empfindung,
mit der Leistung des Produkts einverstanden zu sein und nichts auszuset-
zen zu haben.
• Erfüllung des Wunschs, den empfundenen (oder teilweise auch tatsächli-
chen Mangel) durch das Befolgen der Technischen Dokumentation beho-
ben zu haben, womit die sogenannte erlebte Nutzungsqualität der Erwar-
tungshaltung entspricht
• der Zielgruppe angemessener Wortschatz (bezüglich der Wortlänge, Be-
kanntheit der Worte usw.), Satzbau (Länge, Art, Aufbau) und andere Text-
faktoren
Aussagefähig, verständlich, • Kürze, Einfachheit und Prägnanz, um richtig und schnell verständlich zu
lesbar, klar strukturiert, sein
erlernbar, umsetzbar
• aufgeteilt in Kapitel, die sich soweit möglich inhaltlich nicht überschnei-
den und gemeinsam eine komplette Dokumentation bilden
• angemessene Ergänzung von Texten durch Visualierungselemente
• Einführung von zielgruppenspezifischen Abstraktionsniveaus
• Die gesuchten Einzelthemen lassen sich dank geeigneter Gliederung,
Navigation oder hierarchischer Ordnung schnell auffinden.
• optimale Gestaltung der Navigations- und Orientierungselemente
• Stichwortverzeichnis und Inhaltsverzeichnis (bei Bildschirmdokumenten
möglichst mit Verlinkung auf den Text)
Wirtschaftlichkeit • automatisiert erstellbar und änderbar (systematische Modularisierung)
• Korrekturen und Ergänzungen sollen im wirtschaftlichen Sinne effizient
und kostengünstig sein.
• mehrfach verwendbar (Single-Source-Publishing, Cross-Media-Publi-
shing)

– 52 – VDI 4500 Blatt 4 / Part 4


Quality management
Weak point analysis

• naming of possible exceptions and special cases


• naming of options which are possibly not available or can be added at a
later date
• Does the structuring correspond to the statutory requirements and norma-
tive specifications?
Unambiguity, consistency, • Standardisation of concepts and appellation. Advantageous in this respect
contradictions is the existence of rules that help to achieve and control this standardisa-
tion (terminology specifications).
• uniformity of formulations, e.g. always “turn in the screw”, not alter-
nately “screw in the screw” or “tighten the screw”

• correctness of all links in the texts, no unresolved cross-references


Redundancies • avoidance of repetition of content (exceptions: word repetitions and such
content repetitions that help to avoid unnecessary searching by the user)

• Too frequent use of cross-references should be avoided. The necessity of


frequent leafing through and scrolling in the document reduces efficiency
for the reader and interrupts the flow of the reading experience.
Fitness for use by the • contents that are composed for the specified target group and within a
target group given context of use with the adequate amount of precision

• adjusted to the knowledge that is assumed to exist, adjusted to the intelli-


gence and the context of use of the target group as well as adapted to the
estimated socio-cultural and psychological properties of the target group

• “Satisfactory”: The user perceives the emotional feeling of being satisfied


with the product and not having any objections.

• fulfilment of the wish of having eliminated the perceived (or in part actual
defect) by following the technical documentation, whereby the so-called
experienced quality in use meets the expectations

• vocabulary that is apt for the target group (in respect of word length, level
of awareness of the words, etc.), sentence structure (length, type, struc-
ture) and other text factors
Meaningful, comprehensible, • briefness, simplicity and conciseness, in order to be correctly and quickly
legible, clearly structured, comprehensible
learnable, implementable
• divided into chapters that do not overlap in terms of content as far as pos-
sible and together form a complete piece of documentation
• adequate addition of visualisation elements to the texts
• introduction of target group specific abstraction levels
• The individual topics sought can be quickly found thanks to adequate
structuring, navigation or hierarchical arrangement.
• optimal layout of the navigation and orientation elements
• list of key words and list of contents (in case of display screen documents
preferably with links to the text)
Economic efficiency • can be created and changed automatically (systematic modularisation)
• Corrections and additions should be cost-efficient in the economical
sense.
• multiple use (single source publishing, cross-media publishing)

VDI 4500 Blatt 4 / Part 4 – 53 –


Qualitätsmanagement
Prüfungen am Produkt

Gesetzes- und • konform zu gesetzlichen Anforderungen, produktabhängig


normenkonform
• konform zu hausinternen Regelungen

6.2 Prüfungen am Produkt


Ist die Technische Dokumentation nach einer Checkliste entsprechend den
Prüfkriterien geprüft, sollten auch Akzeptanzprüfungen am Produkt mit unvor-
bereiteten Testpersonen der vorgesehenen Zielgruppe durchgeführt werden.
Gegebenenfalls sind Prüfungen des Produkts durch eine übergeordnete Prüf-
stelle (TÜV, UL, Benannte Stelle) notwendig. Hierbei wird auch die Techni-
sche Dokumentation geprüft.

6.3 Akzeptanzuntersuchungen
Die Technische Dokumentation soll wirksam und sicher das entsprechende
Wissen vermitteln, damit die Benutzer diese Informationen unmittelbar und
ohne Zweifel in Handlungen umsetzen können. Als Kriterien dienen Antwor-
ten auf folgende Fragen:
• Wie lange brauchen Testpersonen bis zur Inbetriebnahme und Nutzung
des Produkts (Bedienschnelligkeit)?
• Welche und wie viele Bedienschritte werden erfolgreich vollzogen?
• Welche der verschiedenen Produktfunktionen werden im ersten Anlauf
genutzt?
• Wie lange dauern die einzelnen Schritte (Soll-Ist-Vergleich)?
• Welche Unklarheiten oder Schwierigkeiten entstehen beim ersten Nutzen
des Produkts?
• Wie hoch ist die Zufriedenheit des Anwenders mit dem Produkt und sei-
ner Bedienung?
• Wie ist die Einstellung des Anwenders zum Produkt (technische Komple-
xität, Bedienungsfreundlichkeit usw.) vor und nach dem Test?
Verfahren • Mit einstufigen Verfahren werden abgeschlossene Benutzerinformationen
vor ihrem Inverkehrbringen geprüft. Nachträgliche Verbesserungen oder
Veränderungen von Produkt und Benutzerinformation sind meist nicht
mehr möglich.
• Bei mehrstufigen Verfahren parallel zur Produktentwicklung können so-
wohl die Produktgestaltung als auch Art, Gestaltung und Inhalt der Benut-
zerinformation zielgruppenkonform beeinflusst werden; sie sind deshalb
gegenüber dem einstufigen Verfahren zu bevorzugen.

Untersuchungsmethoden Für Akzeptanzuntersuchungen stehen verschiedene Methoden zur Verfü-


gung, die unterschiedlich hohen Aufwand erfordern und die an ebenso ver-
schiedene Voraussetzungen gebunden sind. Es werden im Wesentlichen Me-
thoden aus der Marktforschung angewendet (z.B. Lückentest, Behaltens-
oder Erinnerungstest, Eye-Tracking-Tests). Die Auswahl der Methoden, die
Durchführung der Untersuchungen sowie die Interpretation der Ergebnisse
sollten Fachleuten vorbehalten bleiben.
Die Methoden der Akzeptanzuntersuchung können vor oder nach der Produk-
teinführung angewendet werden.
Untersuchungsmethoden Vor der Produkteinführung bieten sich z.B. an:
vor der Markteinführung
• Befragung
Die Befragung von Testpersonen vor oder nach einem Benutzertest unter
gleichzeitiger Beobachtung ihres Verhaltens (siehe unten) ist in der Praxis
die am weitesten verbreitete und wirksamste Methode.

– 54 – VDI 4500 Blatt 4 / Part 4


Quality management
Acceptance tests with the product itself

Consistent with law and • consistent with statutory requirements, product-dependent


standards
• consistent with in-house rules

6.2 Acceptance tests with the product itself


Once the technical documentation is checked according to the test criteria us-
ing a checklist, acceptance tests should be carried out in practice on the prod-
uct with unprepared test persons of the foreseen target group.
If need be, tests of the product by a superordinate test centre (TÜV, UL, no-
tified agency) are necessary. At this juncture, the technical documentation is
also checked.

6.3 Acceptance tests


The technical documentation should communicate the appropriate knowl-
edge effectively and surely, so that the users can convert these informations
into actions directly and without any doubts. Answers to the following ques-
tions serve as criteria for this:
• How long do the test persons need up to commissioning and use of the
product (promptness of operation)?
• Which and how many operating steps are successfully performed?
• Which of the various product functions are used in the first start-up?

• How long do the individual steps last (target-actual comparison)?


• Which ambiguities or difficulties occur when the product is used for the
first time?
• How high is the satisfaction of the user with the product and its operation?

• How is the attitude of the user towards the product (technical complexity,
service-friendliness, etc.) before and after the test?
Process • Before putting into circulation in the market, concluded user information
is tested using a single-step process. Subsequent improvements or
changes of product and user information are mostly no longer possible.

• In case of multiple-step processes in parallel with the product develop-


ment, both the product design as well as type, layout and content of the
user information can be influenced in a target group oriented way; these
processes are therefore to be preferred as compared to single-step proc-
esses.
Test methods Various methods are available for acceptance tests, which require various de-
grees of effort/expenditure and are likewise subject to various prerequisites.
Essentially, methods from market research are applied (e.g. fill in the blanks
test, recall or memory test, eye-tracking tests). The selection of the methods,
the conduct of the analyses as well as the interpretation of the results should
be reserved for experts.

The methods of acceptance tests can be applied before or after the product in-
troduction.
Test methods Prior to product entry, the following methods present themselves:
prior to market entry
• survey
Survey of test persons before or after a user test while simultaneously ob-
serving their behaviour (see below) is the most widespread and effective
method in practice.

VDI 4500 Blatt 4 / Part 4 – 55 –


Qualitätsmanagement
Anforderungen an den Technischen Redakteur

• Beobachtung
Bei diesem Test wird das Produkt mit seiner Benutzerinformation verschie-
denen Testpersonen zur Verfügung gestellt. Bei der Beobachtung nehmen
die Testpersonen mithilfe der Externen Technischen Dokumentation das
Produkt in Betrieb, vollziehen Bedienschritte nach oder führen Produktan-
wendungen durch. Die Beobachtung erfolgt offen, das heißt, der Testperson
ist bewusst, dass sie beobachtet wird. Das Erfüllen der Zielvorgaben, Be-
dienschnelligkeit, erfolgreich absolvierte Bedienschritte sowie benötigte
Zeiten lassen sich auch durch Nichtfachleute zweifelsfrei und direkt aus-
wertbar ermitteln. Die Aufzeichnung der Versuchsdaten sollte durch techni-
sche Hilfsmittel (Audio-/Videoaufzeichnung) unterstützt werden.
• interne Vorprüfungen
Anhand von Checklisten werden von Mitarbeitern unterschiedlichster Ab-
teilungen (z.B. Marketing, Vertrieb, Service, Technische Redaktion) ein-
zelne Forderungen auf ihre Erfüllung hin überprüft, um Verbesserungs-
oder Änderungsbedarf zu ermitteln. Die Checklisten sind nach den Prüf-
kriterien (siehe oben) produktspezifisch und anwendungsbezogen zu er-
stellen.
Des Weiteren können Labortests mit Prototypen, Expertenbefragungen sowie
spezielle Anwendertests durchgeführt werden. Bei Letzteren wird unterschie-
den zwischen
• internen Tests
(mit Mitarbeitern des Herstellers, Händlern oder Verkaufspersonal) und
• externen Tests
(mit Mitarbeitern wichtiger Kunden oder zufällig ausgewählten Erstbe-
nutzern der Zielgruppe).
Mit diesen Methoden zur Akzeptanzprüfung sind sowohl Produktgestaltung
als auch Inhalte von Technischer Dokumentation wiederholt zu überprüfen.
Die Freigabe zur Fertigung des Produkts und des endgültigen Inhalts der
Technischen Dokumentation sollte erst nach Abschluss dieser Prüfungen und
nach ihrem gezielten Auswerten durch die für Gestaltung, Vertrieb und Kun-
dendienst verantwortlichen Führungskräfte erfolgen.
Besonders wichtig ist der Nachweis der Erfüllung aller Sicherheitsanforde-
rungen aus Rechtsnormen und allgemein anerkannten Regeln der Technik.
Untersuchungsmethoden nach Auch nach der Produkteinführung können Akzeptanzuntersuchungen, z.B.
Markteinführung durch Expertenbefragungen, nützlich sein. Dabei werden das Wissen und die
praktische Erfahrung externer Spezialisten oder Gutachter genutzt.
Es können auch Organisationen wie die Stiftung Warentest, Verbraucherorga-
nisationen oder Technische Überwachungsvereine hinzugezogen werden.
Empfehlenswert ist es, bei Prüfungen erfahrene Mitarbeiter des Verkaufs oder
des Kundendiensts einzubeziehen, die Erkenntnisse aus der Nutzung ähnli-
cher Produkte einbringen können.

6.4 Anforderungen an den Technischen Redakteur


Ausbildung und Qualifikation des Erstellers von Technischer Dokumenta-
tion, des „Technischen Redakteurs“, spielen bei der Qualitätsdefinition eine
wesentliche Rolle. Das Aufgabenfeld des Technischen Redakteurs ist ange-
sichts der vielfältigen Arbeitsbereiche höchst komplex und entsprechend an-
spruchsvoll hinsichtlich der fachlichen und sozialen Kompetenz.
Der Technische Redakteur beschreibt Produkte in verständlicher Sprache und
macht sie dem Nutzer zugänglich. Er ist „Mittler“ zwischen Produkthersteller
und Anwender. Aus heutiger Sicht ist der Technische Redakteur für das ge-

– 56 – VDI 4500 Blatt 4 / Part 4


Quality management
Requirements that the technical writer must meet

• monitoring
In this test, the product with its user information is made available to vari-
ous test persons. In the monitoring phase, the test persons put the product
into operation with the help of the external documentation, reproduce op-
erating steps or apply the product. The monitoring is done openly, i.e. the
test person is aware that he is being observed. The fulfilment of target
specifications, promptness of operation, successfully concluded operating
steps as well as the required time spans can be determined and evaluated
even by non-specialist persons unambiguously and directly. The recording
of test data should be supported by technical aids (audio-/video record-
ing).
• internal preliminary tests
Based on checklists, employees from diverse departments (e.g. marketing,
distribution, service, technical editorial department) check individual re-
quirements for their fulfilment, to determine any need for improvement or
change. The checklists must be product-specific and use-oriented accord-
ing to the test criteria (see above).

Moreover, laboratory tests with prototypes, expert surveys as well as special


user tests are carried out. In the latter case, a distinction is made between

• internal tests
(with employees of the manufacturer, dealer or sales staff) and
• external tests
(with employees of important customers or accidentally selected first us-
ers of the target group).
Both product design and contents of technical documentation are to be repeat-
edly tested with these methods for the acceptance test. The approval for pro-
duction of the product and of the final contents of the technical documenta-
tion should be given only after conclusion of these tests and after their selec-
tive evaluation by the senior managers responsible for design, distribution
and customer service.

Especially important is the proof of fulfilment of all safety requirements


based on legal standards and generally acknowledged rules of technology.
Test methods Even after product entry in the market, acceptance tests can be useful, e.g. us-
after market entry ing surveys addressed at experts. In the process, the knowledge and the prac-
tical experience of external specialists or appraisers are used.
Organisations such as Stiftung Warentest, consumer organisations or techni-
cal surveillance agencies can also be drawn upon. It is recommendable to in-
clude experienced employees from sales and customer service during tests,
who can contribute their findings based on use of similar products.

6.4 Requirements that the technical writer must meet


Education and qualification of the author of the technical documentation, of
the “technical writer”, play an important role while defining quality. The field
of activities of the technical writer is highly complex in view of the manifold
areas of work and is accordingly challenging in terms of technical and social
competence.
The technical writer describes products in comprehensible language and
makes it accessible to the user. He is an “intermediary” between product man-
ufacturer and user. From the present-day point of view, the technical writer is

VDI 4500 Blatt 4 / Part 4 – 57 –


Qualitätsmanagement
Anforderungen an den Technischen Redakteur

samte Informationsmanagement zuständig. Ihm unterliegt die betriebliche


Planung der Dokumentationsbereitstellung, er stellt das im Unternehmen be-
nötigte Wissen zur Verfügung und vermittelt zwischen den Abteilungen und
zwischen Hersteller und Kunden. Um diese anspruchsvolle Aufgabe erfüllen
zu können, ist eine umfangreiche Ausbildung und ein hoher Grad an Syste-
matik und Zuverlässigkeit notwendig. Ausbildungsgänge mit dem Abschluss
des Technischen Redakteurs werden an vielen Hochschulen und als Weiter-
bildungsangebot bei Weiterbildungsorganisationen, freien Bildungsträgern
und Berufsverbänden angeboten.
Aufgrund seiner didaktischen Fähigkeiten muss der Technische Redakteur in
der Lage sein, komplexe technische Inhalte verständlich, zielgruppengerecht,
übersichtlich und in logischer Form sachlich richtig darzustellen. Er muss in
der Lage sein, technische Gegebenheiten aus verschiedenen Sichtweisen zu
betrachten. Bei der Erstellung einer Dokumentation im eigenen Haus kann er
gegebenenfalls aus der Blickrichtung des Anwenders korrigierend Einfluss
auf die Entwicklung nehmen.
Der Technische Redakteur ist verantwortlich für die Zeit- und Ressourcenpla-
nung der zu erstellenden Dokumente:
• Termine
• Personal
• Auftragsvergabe an andere Abteilungen oder Dienstleister
• Kosten
• Arbeitsmittel
Zu den Aufgaben des Technischen Redakteurs gehören unter anderem:
• Analysieren (Produkt- und Zielgruppenanalyse, Prüfung rechtlicher Be-
dingungen, Restgefahren für Sicherheitshinweise auswerten)
• Sammeln und Selektieren von Informationen
• Auswahl des geeigneten Publikationsmediums (Online, Print, CD-ROM
u.a.)
• Konzipieren (endgültiges Festlegen des Gesamtkonzepts, der einzelnen
Teile, der Realisierungsschritte)
• Erstellen des Endmanuskripts (Verfassen der Texte, Erstellen bzw. Beauf-
tragen der zugehörigen Grafiken, Illustrationen und Fotos, Übersetzungen
in andere Sprachen)
• interner Praxistest
• Korrekturlauf
• Endkorrektur
• Vorbereitung, Veranlassung und Überwachung der Herstellung (wie Satz,
Druck)
• Aktualisieren, Ändern, Überarbeiten
• Archivieren und Verwalten der erstellten Dokumentationen
Die fertige Technische Dokumentation muss ihre Funktion als Kommunika-
tionsmittel zwischen Hersteller und Anwender erfüllen. Sie muss sehr hohen
Qualitätsanforderungen bezüglich Inhalt und Gestaltung gerecht werden. Das
zu erreichen und zu verwirklichen ist Aufgabe des Technischen Redakteurs.

– 58 – VDI 4500 Blatt 4 / Part 4


Quality management
Requirements that the technical writer must meet

responsible for the entire information management. He is responsible for the


operational planning of document provision, he makes available the knowl-
edge needed within the company and mediates between the departments and
between manufacturer and customer. To be able to fulfil this challenging job,
extensive education and a high degree of systematic methodology and relia-
bility is required. Educational courses with leaving examination for qualifica-
tion as technical writer are offered at many colleges and are also offered as
further education courses at further educational institutes, by independent ed-
ucational institutions and professional associations.
Based on his didactic ability, the technical writer must be in a position to rep-
resent complex technical contents in an understandable, target-group ori-
ented, clearly arranged, logical and factually correct way. He must be in a po-
sition to regard technical facts and circumstances from various perspectives.
While creating a piece of in-house documentation, he can possibly exert a
corrective influence on development from the perspective of the user.

The technical writer is responsible for time and resource planning of the doc-
uments to be created:
• deadlines
• personnel
• assignment of order to other departments or service providers
• costs
• work equipment
The tasks of a technical writer include, among others:
• analysing (product and target group analysis, check of legal conditions,
assessment of residual risks for safety instructions)
• collecting and selecting of information
• selection of the suitable publication medium (online, print, CD-ROM and
the like)
• conception (final definition of the overall concept, of the individual parts,
of the implementation steps)
• creation of the final manuscript (formulation of the texts, creation or as-
signing the creation of the corresponding graphics, illustrations and pho-
tos, translations into other languages)
• internal practical test
• correction run
• final correction
• preparation, initiation and monitoring of production (such as set, print)

• updating, changing, revising


• archiving and management of the created documentation
The final technical documentation must fulfil its function as means of com-
munication between manufacturer and user. It must meet very high quality re-
quirements with respect to content and layout. It is the task of the technical
writer to realise this.

VDI 4500 Blatt 4 / Part 4 – 59 –


Glossar
Anforderungen an den Technischen Redakteur

Glossar
After-Sales-Konzept Konzept sämtlicher Maßnahmen des Unternehmens, um den Kunden nach
dem Kauf eines Produkts oder einer Dienstleistung von der Richtigkeit seiner
Entscheidung zu überzeugen, bei der Anwendung zu unterstützen und ihn an
das eigene Geschäft zu binden.
Anmerkung: Unternehmen mit einer optimal zugeschnittenen Umsetzung des After-Sales-Kon-
zepts können damit wesentlich zu Profitabilität des Unternehmens beitragen. Hierbei gilt der
Grundsatz: „Nach dem Kauf ist vor dem Kauf“.

Cross-Media-Publishing Eine medienübergreifende Veröffentlichung. Hierbei ist die Erstellung von


Technischer Dokumentation auf unterschiedlichen Medien (gedruckte Mate-
rialien, CD-ROM, Internet usw.) möglich, wobei jedoch eine einheitliche Da-
tenbasis genutzt werden kann. Diese einheitliche Datenbasis wird medien-
neutral verwaltet und gespeichert. Texte, Bilder und andere grafische Ele-
mente können ohne Verfälschungen gespeichert werden, und die endgültige
Formatierung erfolgt erst später – mediengerecht.
Anmerkung: Es ist ein Lösungskonzept, das immer wichtiger wird, weil sich damit Einsparungen
erzielen lassen.

Dokumentation Durchgängige, systematische Zusammenfassung und Bearbeitung von aufge-


zeichneten Informationen zum Aufbewahren, Klassifizieren, Wiederfinden,
Nutzen und Verbreiten. [in Anlehnung an ISO 5127-1]

Externe Technische Beinhaltet alle technischen Informationen über Produkte, die von einem Her-
Dokumentation steller/Vertreiber für Vertrieb, Anwender und Verbraucher bestimmt sind, und
dient der Produktnutzung durch den Anwender.
Anmerkung: Die Dokumentenarten und Dokumentationsprozesse können vielfältig sein. Qualität
und Verständlichkeit der Externen Technischen Dokumentation bestimmen, ob und inwieweit die
jeweiligen Zielgruppen die angebotenen Leistungen und Funktionen der Produkte vorteilhaft für
sich nutzen können. Marketingunterlagen müssen ebenfalls in die Dokumentationsprozesse mit
einbezogen werden.

Hamburger Ein bekannt gewordenes Modell über verständliche und erfolgreiche Sprache.
Verständlichkeitsmodell Es werden vier „Verständlichmacher“ dargestellt: Einfachheit, Gliederung und
Ordnung, Kürze und Prägnanz sowie schließlich die zusätzliche Stimulanz.
Die jeweilige Gruppe wird weiter untersucht bzw. verfeinert und benotet.
Anmerkung: Innerhalb der Gruppe Einfachheit wird beispielsweise zwischen kurzen, einfachen
Sätze und langen, verschachtelten Sätzen unterschieden und dafür Noten auf einer Skala von 2 für
die einen bis zu –2 für die anderen vergeben.

Infrastruktur Langlebige Grundeinrichtungen personeller, materieller oder institutioneller


Art.

Interne Technische Beinhaltet alle technischen Informationen über ein Produkt, die im Unterneh-
Dokumentation men verbleiben.
Anmerkung: Interne Technische Dokumentation muss sämtliche Produktentwicklungsschritte als
Nachweis transparent, reproduzierbar und nachvollziehbar festhalten – von der Produktanalyse
bis hin zur Entsorgung. Über den Umfang einer Internen Technischen Dokumentation zu einem
Produkt entscheidet immer allein der Hersteller entsprechend den gesetzlichen Forderungen und
der Verantwortung gegenüber den Kunden.

Lastenheft Beschreibt die Gesamtheit der Forderungen des Auftraggebers.


Anmerkung 1: Im →Pflichtenheft ist in konkreterer Form beschrieben, wie der Auftragnehmer
die Anforderungen aus dem Lastenheft zu lösen gedenkt.
Anmerkung 2: Siehe auch VDI 2519 Blatt 1.

Layout Englisch für „Plan, Entwurf, Anlage“, bezeichnet das Design innerhalb der
→Technischen Dokumentation, um einen ausgewogenen und geordneten
visuellen Eindruck zu erwecken und einen günstigen Lesefluss zu ermög-
lichen.

– 60 – VDI 4500 Blatt 4 / Part 4


Glossary
Requirements that the technical writer must meet

Glossary
After-sales-concept Concept of all measures of the company, in order to convince the customer of
the correctness of his decision after the purchase of a product or a service, to
support the user in making use of the product/service and to bind him to his
purchase.
Note: Companies with an optimal implementation of the after-sales-concept can therewith con-
tribute significantly to the profitability of the company. The maxim that applies here is: “after-
sales is pre-sales”.

Cross-media-publishing Creation of technical documentation on different media (printed material,


CD-ROM, internet, etc.), with the possibility of using a standardised database
which manages and stores texts, images and other graphic elements without
falsification. The final formatting will be done later – different for each indi-
vidual medium.

Note: It is a solution concept that is becoming ever more important, because it permits savings to
be achieved.

Documentation Continuous, systematic summarisation and processing of recorded informa-


tion for retention, classification, recovery, use and dissemination. [adapted
from ISO 5127-1]

External technical Technical manufacturer/distributor information about products that are meant
documentation for distribution, users and consumers and serve the purpose of product use.

Note: The document types and documentation processes can be diverse. Quality and comprehen-
sibility of the external technical documentation determine as to whether and to what extent the re-
spective target groups can use the offered services and functions of the product to their advantage.
Marketing documents must be likewise included in the documentation processes.

Hamburg model of Model of comprehensible and successful language in technical documenta-


comprehensibility tion, which prioritises the following comprehension criteria: simplicity, struc-
turing and order, briefness and conciseness as well as the additional stimula-
tion. The criteria are further sub-divided and evaluated.
Note: For example, in the group “simplicity” a difference is drawn between short, simple sen-
tences and long, complicated sentences. For this, the types of sentences are marked on a scale from
2 (for the first) to –2 (for the last).

Infrastructure Long-lasting basic facilities that are personnel-based or are material or insti-
tutional in nature.

Internal technical Technical information about products that remain in the company, for in-
documentation stance, information pertaining to development, test and production.
Note: Internal technical documentation must record in writing all the product development steps
as evidence that is transparent, reproducible and retraceable – from the product analysis up to the
disposal processes. The manufacturer alone decides about the extent of internal technical docu-
mentation about a product according to the statutory requirements and the responsibility vis-a-vis
the customer.

Tender specifications Describes the totality of requirements of the awarding authority.


Note 1: In the performance specifications, it is described in concrete terms as to how the contrac-
tor intends to satisfy the requirements in the tender specifications.
Note 2: See also VDI 2519 Part 1.

Layout Layout (plan, design) within →technical documentation denotes the design
used to create a balanced and orderly visual impression and to permit a fa-
vourable flow of reading experience.

VDI 4500 Blatt 4 / Part 4 – 61 –


Glossar
Anforderungen an den Technischen Redakteur

Anmerkung: Hierbei geht es beispielsweise um eine eindeutige Trennung von Spalten, die Be-
grenzung von Zeilenlängen, Festlegung von Leit- und Ergänzungsmedien, Entscheidungen über
den Einsatz von Farben und vieles mehr.

Modularisierung Eine Vorgehensweise der Aufteilung eines Ganzen in Teile, um komplexe


Prozesse und Verfahren effizienter zu gestalten.
Anmerkung: Hierbei gilt der Grundsatz, dass die Änderungen innerhalb von einem der Module
sich nicht auf andere Module auswirken soll. Im Sinne der →Technischen Dokumentation lässt
sich mittels der Modularität die Verständlichkeit von komplexen Zusammenhängen für den Men-
schen verbessern.

Persona-Methode Etabliertes Verfahren für die Durchführung einer →Zielgruppenanalyse.

Pflichtenheft Dokument, das in konkreterer Form beschreibt, auf welche Weise die pro-
dukt- und dokumentationsspezifischen Anforderungen des →Lastenhefts
verbindlich festgeschrieben werden. Laut DIN 69905 sind dies „die vom
Auftragnehmer erarbeiteten Realisierungsvorgaben aufgrund der Umsetzung
des vom Auftraggeber vorgegebenen Lastenhefts“.
Anmerkung: Es wird vom Auftragnehmer formuliert und auf dessen Wunsch vom Auftraggeber
bestätigt.

Produktlebenszyklus Modell, das die „Lebensdauer“ eines Produkts in mehrere Phasen unterteilt (siehe
Bild 3).

Qualitätsmanagement Maßnahmen des Managements, die der Verbesserung von Produkten bzw. der
Erreichung der vorgegebenen Qualität dienen. Es umfasst die Optimierung
von Kommunikationsstrukturen, Definition der dafür erforderlichen Verant-
wortlichkeiten, Prozesse und erforderlichen Mittel für die Qualitätspolitik ei-
nes Unternehmens oder einer Organisation.
Anmerkung: Das Qualitätsmanagement ist in der ISO-9000-Familie beschrieben, aber auch in
anderen Normen wie DIN EN ISO/IEC 17 025.

Redaktionshandbuch Vom Technischen Redakteur mit dem Ziel erstelltes Dokument, technische
Dokumentation zu erleichtern, zu rationalisieren und zu vereinheitlichen.
Anmerkung: Neben Style-Guides, das heißt Gestaltungsrichtlinien für die zu erstellenden Doku-
mente, sollte es Arbeitsanweisungen, Checklisten und andere Hilfsmittel enthalten.

Ressourcen Bestand der Betriebsmittel bzw. Produktionsfaktoren (Hilfsmittel), Geldmit-


tel, Personen und (Arbeits-)Zeit, die notwendig sind, um den Vorgang der Er-
stellung der →Technischen Dokumentation ablaufen zu lassen.

Risikoanalyse Die Risikoanalyse ist der Prozess, um Gefährdungen und deren Ursachen zu
erkennen sowie deren Risiken qualitativ und quantitativ zu erfassen.

Risikobewertung Die Risikobewertung ist ein strukturierter Vorgang zur Identifizierung


(→Risikoanalyse) und zur Bewertung von Risiken. Die Bewertung beginnt
mit der Bestandsaufnahme potenzieller Gefahren und damit verbundenen Ri-
siken, ihrer Eintrittswahrscheinlichkeit und möglichen Folgen. Die so bewer-
teten Risiken werden dann mit vorher definierten Risikokriterien abgegli-
chen.

SGML SGML (Standard Generalized Markup Language, generalisierte Standardaus-


zeichnungssprache); Metasprache zur einheitlichen Definition unterschied-
licher Auszeichnungssprachen für Dokumente (siehe auch →XML).
Anmerkung: Einer der Väter von SGML ist Charles Goldfarb, der die Grundlagen für IBMs Do-
cument Composing Facility Generalized Markup Language (DCF GML) definierte. Die Weiter-
entwicklung von GML führte zum SGML als internationalem Standard: ISO 8879:1986. Auf der
Basis von SGML sind beispielsweise XML und HTML aufgebaut. In SGML ist der Inhalt des Do-
kuments durch Elemente definiert bzw. strukturiert. Diese Elemente werden jeweils durch einen
„Tag“ („Etikett“, „Markierung“) dargestellt. Tags sind Kürzel, die in spitzen Klammern einge-
schlossen sind, und dienen dazu, Textelemente auszuzeichnen. SGML bietet ideale Voraussetzun-
gen für die Erstellung von Dokumenten auf Grundlage einer Datenbasis.

– 62 – VDI 4500 Blatt 4 / Part 4


Glossary
Requirements that the technical writer must meet

Note: Important here is, for instance, a clear separation of columns, restricted row lengths, spec-
ification of dominant media and supplementary media, decisions about the use of colours and
much more.

Modularisation A procedure of division of a whole into parts, in order to design complex


processes more efficiently.
Note: The principle that applies here is that a change in one of the modules should not have any
influence on other modules. In terms of →technical documentation, the comprehensibility of com-
plex contexts can be improved for people with the help of modularity.

Persona method Established procedure for realising →target group analysis

Performance Document that describes in concrete terms as the way in which the product-
specifications and documentation-specific requirements of the →tender specifications shall
be recorded in writing as binding. According to DIN 69905, these are “reali-
sation specifications developed by the contractor based on the implementa-
tion of the tender specifications given by the awarding authority”.
Note: It is formulated by the contractor, who asks the awarding authority to confirm it.

Product lifecycle Model that sub-divides the “lifecycle” of a product into several phases (see
Figure 3).

Quality management Measures of the management, which serve to improve the products and/or
achieve the specified quality. It includes the optimisation of communication
structures, definition of the responsibilities, processes and means required for
the quality management policy of a company or an organisation.

Note: Quality management is described in the ISO-9000 family of standards as well as in other
standards such as DIN EN ISO/IEC 17025.

Editorial manual Document authored by the technical writer with the aim of simplifying, ra-
tionalising and standardising technical documentation.
Note: In addition to style-guides, i.e. layout guidelines for the documents to be created, it should
contain work instructions, checklists and other aids.

Resources Stock of operating resources and/or production factors (auxiliary materials),


funds, persons and (working) hours, that are needed to allow the process of
→technical documentation to run.

Risk analysis The risk analysis is the process, to recognise risks and compile their causes as
well as their risks qualitatively and quantitatively.

Risk estimation Risk estimation is a structured process for identification (→risk analysis) and
evaluation of risks. The evaluation starts with the stocktaking of potential
hazards and the associated risks, their probability of occurrence and their pos-
sible consequences. The risks thus evaluated are then reconciled with previ-
ously defined risk criteria.

SGML SGML (standard generalised markup language); metalanguage for standard-


ised definition of various markup languages for documents (see also
→XML).
Note: One of the fathers of SGML is Charles Goldfarb, who defined the basic principles for
IBM‘s Document Composing Facility Generalised Markup Language (DCF GML). The further
development of GML resulted in SGML as international standard: ISO 8879:1986. XML and
HTML are for instance composed on the basis of SGML. In SGML, the content of the document
is defined with the help of elements or structured. These elements are respectively represented
with the help of a “tag” (“label”, “marking”). Tags are short forms that are enclosed in angle brack-
ets, and serve to mark up text elements. SGML offers ideal prerequisites for the creation of docu-
ments on the basis of a database.

VDI 4500 Blatt 4 / Part 4 – 63 –


Glossar
Anforderungen an den Technischen Redakteur

Single-Source- Verfahren für die Verwaltung, Lenkung, Archivierung und Bereitstellung


Publishing elektronisch erfasster Dokumente. Das wesentliche Ziel ist das mehrfache
Verwenden vorhandener Daten, um aus einer Quelle („Single-Source“) eine
ganze Palette flexibler Möglichkeiten verschiedener Ausgabeformate zu er-
reichen.

SAFE-Methode Handlungsbezogene Warnhinweise mit folgenden Elementen:


• Hinweis auf die Schwere der Restgefahr durch Verwendung genormter
Signalwörter (nach DIN ISO 3864-2) mit genormtem Warnzeichen (nach
DIN 4844-2, BGV A 8, DIN EN 61310 und ISO 7010, für die USA:
ANSI Z 535.6)
• Art und Quelle der Restgefahr
• mögliche Folgen bei Missachtung der Restgefahr
• Maßnahmen zum Abwenden der Restgefahr
Anmerkung: Als Eselsbrücke zum Merken der vier wesentlichen Elemente dient das Akronym
SAFE für Signalwort mit Symbol, Art und Quelle der Restgefahr, Folge der Missachtung, Ent-
kommen.

Technische Sammelbegriff für alle Dokumente über technische Produkte, Prozesse und
Dokumentation (TD) deren Einsatz und Verwendung.
Anmerkung: Die Technische Dokumentation muss in übersichtlicher und logischer Form sach-
lich richtig alle Informationen bereitstellen, die zweckentsprechend von ihr erwartet werden, z.B.
für Akquisition, Verkauf, Projektierung, Montage, Betrieb, Instandhaltung, Entsorgung. Dies ge-
schieht in Form von →Lasten- und →Pflichtenheften, Werbeschriften, Produktbeschreibungen,
Gebrauchs- und Betriebsanleitungen, Wartungshandbüchern, Teilekatalogen, Programmieranlei-
tungen u.a.

Unternehmensprozess Kernprozesse, Führungsprozesse und Unterstützungsprozesse eines Unter-


nehmens.
Anmerkung: Nach ISO 9001 muss das Management eines Unternehmens die Hauptprozesse be-
nennen, die mit der Produktion oder Dienstleistungserbringung unmittelbar im Zusammenhang
stehen. Außerdem sollte die oberste Leitung die übrigen Prozesse ermitteln, die die Wirksamkeit
dieser Hauptprozesse und/oder die Erfordernisse der interessierten Parteien beeinflussen. Das Ge-
schäftsprozessmodell spielt eine wichtige Rolle, weil es die Grundlage für die Einführung eines
prozessorientierten Qualitätsmanagements ist.

Wer-macht-was-Matrix Verfahren zur Durchführung einer Zielgruppenanalyse. Die durchzuführen-


den Tätigkeiten über den gesamten Produktlebenszyklus werden in einer ge-
ordneten Matrix erfasst und den typischen Ausführenden zugeordnet. Hierbei
ergibt sich eine eindeutige Zuordnung der Aufgaben zu den Nutzern und die
daraus folgende Klassifizierung der Dokumente (siehe auch →Zielgruppe,
→Zielgruppenanalyse, →Persona-Methode).
Anmerkung: Dieses Verfahren hat sich in der Praxis bewährt, um zu einer Klassifikation der Nut-
zer hinsichtlich ihrer Tätigkeiten und typischen Erfahrungen zu kommen.

XML XML (Extensible Markup Language, erweiterbare Auszeichnungsspra-


che). XML ist auf der Basis von →SGML aufgebaut und ist inzwischen ein
weltweit anerkanntes Austauschformat für Daten, weil seine Ausrichtung als
medienneutrales Datenformat für die Datenhaltung und Verarbeitung viele Vor-
teile bietet.
Anmerkung: XML-Dokumente sehen ähnlich aus wie HTML-Dokumente: Sie enthalten in spitze
Klammern eingefasste „Tags“. Im Unterschied zu HTML ist beim XML kein einziger Element-
Typ („Tag“) von der Bedeutung her von vornherein definiert. Das bedeutet, dass jeder seine eige-
nen Elemente und somit ein eigenes Vokabular zusammenstellen kann.

XPS XPS (XML Paper Specification). Ein neues Dateiformat für Dokumente, um
elektronische Unterlagen in eine allgemein lesbare Form zu bringen.
Anmerkung: Es ist als eine Alternative zum Adobe ® Portable Document Format (PDF) von der
Firma Microsoft® entwickelt. Dieses Dateiformat wurde 2005 erstmals vorgestellt und soll für
hochwertige Ausdrucke, erleichterten Datenaustausch und erhöhte Dokumentensicherheit sorgen.

– 64 – VDI 4500 Blatt 4 / Part 4


Glossary
Requirements that the technical writer must meet

Single-source publishing Procedure for the management, control, archiving and provision of electroni-
cally composed documents. The basic aim is the multiple uses of available data,
in order to achieve an entire palette of flexible options for various output for-
mats from a single source.

SAFE method Action-oriented warnings with the following elements:


• pointer to the seriousness of the residual risk by using standardised signal
words (according to DIN ISO 3864-2) with standardised warning signs
(according to DIN 4844-2, BGV A 8, DIN EN 61310 and ISO 7010, for
the USA: ANSI Z 535.6)
• type and source of residual risk
• possible consequences of disregard of residual risks
• measures for avoidance of residual risks
Note: The acronym SAFE for signal word serves as a mnemonic for memorising the four essential
elements of symbol, type and source of residual risk, consequences of disregard of warning, es-
cape.

Technical Collective term for all documents about technical products, processes and
documentation (TD) their deployment and use.
Note: Technical documentation must make available all information that is expected of it expedi-
ently in clearly arranged, logical and factually correct way, e.g. for acquisition, sale, project engi-
neering, installation, operation, servicing, disposal. This happens in the form of →tender specifi-
cations and →performance specifications, advertising copy, product descriptions, user guides and
operating instructions, maintenance manuals, parts catalogues, programming instructions and the
like.

Company processes Core processes, management processes and support processes of a company.

Note: According to ISO 9001, the management of a company must name the main processes
which are directly connected to the production or service provision. Furthermore, the top manage-
ment must determine the remaining processes, which influence the effectiveness of these main
processes and/or the requirements of the interested parties. The business process model plays an
important role, because it is the basis for the introduction of a process-oriented quality manage-
ment.

Who-makes-what matrix Process of target group analysis in the course of which activities to be carried
out over the entire product lifecycle are compiled in a well-arranged matrix
and are assigned to the typical executives. At this juncture, there is an explicit
assignment of the tasks to the users and the resultant classification of the doc-
uments (see also →target group, →target group analysis, →persona method).

Note: This procedure has proved its worth in practice for the purpose of arriving at a classification
of the users in respect of their activity and typical experiences.

XML XML (extensible markup language) is based on →SGML and is meanwhile


an exchange format for data acknowledged worldwide, because its orienta-
tion as a media-neutral data format offers many advantages for data mainte-
nance and processing.

Note: XML documents appear similar to HTML documents: They contain “tags” enclosed in an-
gle brackets. Unlike HTML, no single element type (“tag”) in XML is predefined in terms of its
meaning. This implies that each person can compile his own elements and his own vocabulary.

XPS Abbreviation for “XML paper specification”. A new file format for documents,
in order to convert electronic documents into a generally legible format.
Note: It has been developed by Microsoft® as an alternative to Adobe® Portable Document Format
(PDF). This file format was presented for the first time in 2005 and shall ensure high-value print-
outs, simplified data exchange and increased document protection. XPS is a fixed component of

VDI 4500 Blatt 4 / Part 4 – 65 –


Glossar
Anforderungen an den Technischen Redakteur

XPS ist fester Bestandteil von 2007 Microsoft Office® und Microsoft Windows Vista®, aber es ist
grundsätzlich plattformunabhängig und steht lizenzfrei zur Verfügung.

Zielgruppe Eine definierte Personengruppe mit vergleichbaren Merkmalen, an die sich


die →Technische Dokumentation richtet. Die Beschreibung einer Zielgruppe
erfolgt z.B. kategorisiert nach Alter, Wissen, Benutzungskontext, soziokultu-
relle und psychologische Eigenschaften, Sprachverständnis, Produkterfah-
rung, Technikverständnis.
Anmerkung: Die Zielgruppe muss in der Technischen Dokumentation genannt werden. Dies ver-
meidet Fehlanwendungen und ist z.B. seitens des Produkthaftungsgesetzes geboten.

Zielgruppenanalyse Verfahren zur Ermittlung einer auf die Zielgruppe angepassten →Techni-
schen Dokumentation. Es werden Eigenschaften und das Verhalten von Le-
sern der Technischen Dokumentation untersucht, um eine möglichst gute Ge-
brauchstauglichkeit innerhalb eines gegebenen Benutzungskontexts zu errei-
chen (siehe auch →Persona-Methode, →Wer-macht-was-Matrix).

– 66 – VDI 4500 Blatt 4 / Part 4


Glossary
Requirements that the technical writer must meet

2007 Microsoft Office® and Microsoft Windows Vista®, but it is basically platform-independent
and is available in the public domain.

Target group A defined group of persons with comparable characteristics to which the
→technical documentation is addressed. The description of a target group is
done, for instance, by category of age, knowledge, intelligence, context of
use, socio-cultural and psychological properties, understanding of the lan-
guage, product experience, understanding of technology.
Note: The target group must be mentioned in the technical documentation. This avoids incorrect
use and is, among other things, imperative under the Product Liability Act.

Target group analysis Process for determining a →technical documentation that is adjusted to the
target group. Properties and the behaviour of readers of technical documenta-
tion are analysed, in order to achieve the best possible fitness for use within a
given context of use (see also →persona method, →who-makes-what ma-
trix).

Schrifttum / Bibliography
Gesetze, Verordnungen, Richtlinie 98/37/EG des Europäischen Parlaments und des Rates vom 22. Juni 1998 zur Anglei-
Verwaltungsvorschriften / chung der Rechts- und Verwaltungsvorschriften der Mitgliedstaaten für Maschinen (Direc-
Acts, ordinances, tive 98/37/EC of the European parliament and of the Council of 22 June 1998 on the approxima-
tion of the laws of the member states relating to machinery). Zurückgezogen / Withdrawn 2009-
aministrative regulations
12. Nachfolgedokument 2006/42/EG / Following document 2006/42/EC
Richtlinie 2006/42/EG des Europäischen Parlaments und des Rates vom 17. Mai 2006 über
Maschinen und zur Änderung der Richtlinie 95/16/EG (Neufassung) (Directive 2006/42/EC of
the European Parliament and of the Council of 17 May 2006 on machinery, and amending Direc-
tive 95/16/EC (recast))
Gesetz über technische Arbeitsmittel und Verbraucherprodukte (Geräte- und Produktsicherheits-
gesetz – GPSG) vom 6. Januar 2004 (BGBl I, 2004, Nr. 1, S. 2–20), zuletzt geändert am zuletzt
geändert am 07.03.2011 (BGBl I, 2011, Nr. 9, S. 338–340)

Technische Regeln / ANSI Z 535.6:2011-00 Product Safety Information in Product Manuals, Instructions, and Other
Technical rules Collateral Materials. Washington, D.C.: ANSI
BGV A 8:2002-01 BG-Vorschrift; Sicherheits- und Gesundheitsschutzkennzeichnung am Ar-
beitsplatz. Köln: Carl Heymanns Verlag
DIN 4844-2:2010-12 (Entwurf / Draft) Grafische Symbole; Sicherheitsfarben und Sicherheitszei-
chen; Teil 2: Registrierte Sicherheitszeichen (Graphical symbols; Safety colours and safety signs;
Part 2: Registered safety signs). Berlin: Beuth Verlag
DIN 4844-2:2001-02 Sicherheitskennzeichnung; Teil 2: Darstellung von Sicherheitszeichen
(Safety marking; Part 2: Overview of safety signs). Berlin: Beuth Verlag
DIN 69901-1:2009-01 Projektmanagement; Projektmanagementsysteme; Teil 1: Grundlagen
(Project management; Project management systems; Part 1: Fundamentals). Berlin: Beuth Verlag
DIN 69901-5:2009-01 Projektmanagement; Projektmanagementsysteme; Teil 5: Begriffe
(Project management; Project management systems; Part 5: Concepts). Berlin: Beuth Verlag
DIN 69905:1997-05 Projektwirtschaft; Projektabwicklung; Begriffe (Project business; Perform-
ing of projects; Terminology). Zurückgezogen 2009-01. Nachfolgedokumente DIN 69901-1 und
DIN 69901-5
DIN EN 61310-1*VDE 0113-101:2008-09 Sicherheit von Maschinen; Anzeigen, Kennzeichen
und Bedienen; Teil 1: Anforderungen an sichtbare, hörbare und tastbare Signale (IEC 61310-1:
2007); Deutsche Fassung EN 61 310-1:2008 (Safety of machinery; Indication, marking and actu-
ation; Part 1: Requirements for visual, acoustic and tactile signals (IEC 61 310-1:2007); German
version EN 61310-1:2008). Berlin: Beuth Verlag
DIN EN 61310-2*VDE 0113-102:2008-09 Sicherheit von Maschinen; Anzeigen, Kennzeichen
und Bedienen; Teil 2: Anforderungen an die Kennzeichnung (IEC 61 310-2:2007); Deutsche Fas-
sung EN 61 310-2:2008 (Safety of machinery; Indication, marking and actuation; Part 2: Require-
ments for marking (IEC 61310-2: 2007); German version EN 61310-2:2008). Berlin: Beuth Ver-
lag

VDI 4500 Blatt 4 / Part 4 – 67 –


Schrifttum / Bibliography
Anforderungen an den Technischen Redakteur

DIN EN 61310-3*VDE 0113-103:2008-09 Sicherheit von Maschinen; Anzeigen, Kennzeichen


Schrifttum / Bibliography

und Bedienen; Teil 3: Anforderungen an die Anordnung und den Betrieb von Bedienteilen (Stell-
teilen) (IEC 61310-3:2007); Deutsche Fassung EN 61 310-3:2008 (Safety of machinery; Indica-
tion, marking and actuation; Part 3: Requirements for the location and operation of actuators
(IEC 61310-3:2007); German version EN 61310-3:2008). Berlin: Beuth Verlag
DIN EN ISO 9000:2005-12 Qualitätsmanagementsysteme; Grundlagen und Begriffe (ISO 9000:
2005); Dreisprachige Fassung EN ISO 9000:2005 (Quality management systems; Fundamentals
and vocabulary (ISO 9000:2005); Trilingual version EN ISO 9000:2005). Berlin: Beuth Verlag
DIN EN ISO 9001:2008-12 Qualitätsmanagementsysteme; Anforderungen (ISO 9001:2008);
Dreisprachige Fassung EN ISO 9001:2008 (Quality management systems; Requirements
(ISO 9001:2008); Trilingual version EN ISO 9001:2008). Berlin: Beuth Verlag
DIN ISO 3864-2:2008-07 Grafische Symbole; Sicherheitsfarben und Sicherheitszeichen; Teil 2:
Gestaltungsgrundlagen für Sicherheitsschilder zur Anwendung auf Produkten (ISO 3864-2:2004)
(Graphical symbols; Safety colours and safety signs; Part 2: Design principles for product safety
labels (ISO 3864-2:2004)). Berlin: Beuth Verlag
DIN ISO 15226:1999-10 Technische Produktdokumentation; Lebenszyklusmodell und Zuord-
nung von Dokumenten (ISO 15226:1999) (Technical product documentation; Life cycle model
and allocation of documents (ISO 15226:1999)). Berlin: Beuth Verlag
DIN EN ISO/IEC 17025:2005-08 Allgemeine Anforderungen an die Kompetenz von Prüf- und
Kalibrierlaboratorien (ISO/IEC 17025:2005); Deutsche und englische Fassung EN ISO/
IEC 17025:2005 (General requirements for the competence of testing and calibration laboratories
(ISO/IEC 17 025:2005); German and English version EN ISO/IEC 17025:2005). Berlin: Beuth
Verlag
prEN ISO 7010:2008-01 Graphical symbols; Safety colours and safety signs; Safety signs used in
workplaces and public areas (ISO 7010:2003 including Amd 1:2006 and Amd 2:2007). Genf: ISO
ISO 5127:2001-10 Information and documentation; Vocabulary (Information und Dokumenta-
tion; Begriffe). Genf: ISO
ISO 5127-1:1983-12 Documentation and information; Vocabulary; Part 1: Basic concepts Bilin-
gual edition (Dokumentation und Information; Fachwörterverzeichnis; Teil 1: Grundprinzipien).
Zurückgezogen / Withdrawn 2001-10. Nachfolgedokument / Following document ISO 5127
ISO 7010:2011-06 Graphical symbols; Safety colours and safety signs; Registered safety signs
(Grafische Symbole; Sicherheitsfarben und Sicherheitszeichen; Registrierte Sicherheitszeichen).
Genf: ISOISO 8879:1986-10 Informationsverarbeitung; Text- und Bürosysteme; Verallgemei-
nerte normalisierte Erweiterungssprache (Information processing; Text and office systems; Stan-
dard Generalized Markup Language (SGML)). Genf: ISO
VDI 1000:2010-06 VDI-Richtlinienarbeit; Grundsätze und Anleitungen (VDI Guideline Work;
Principles and procedures). Berlin: Beuth Verlag
VDI 2519 Blatt 1:2001-12 Vorgehensweise bei der Erstellung von Lasten-/Pflichtenheften (Pro-
cedures for the compilation of tender and performance specifications). Berlin: Beuth Verlag
VDI 4500 Blatt 1:2006-06 Technische Dokumentation; Begriffsdefinitionen und rechtliche
Grundlagen (Technical documentation; Definitions and legal basics). Berlin: Beuth Verlag
VDI 4500 Blatt 2:2006-11 Technische Dokumentation; Organisieren und Verwalten (Technical
documentation; Organization and management). Berlin: Beuth Verlag
VDI 4500 Blatt 3:2006-06 Technische Dokumentation; Erstellen und Verteilen von elektroni-
schen Ersatzteilinformationen (Technical documentation; Producing and distributing electronic
spare parts information). Berlin: Beuth Verlag

Weiterführende Literatur / Rechenberg, P.: Technisches Schreiben (nicht nur) für Informatiker. München, Wien: Carl Hanser
Continuative literature Verlag, ISBN 10 3-446-40695-6
Hennig, J.; M. Tjarks-Sobhani: Wörterbuch zur technischen Kommunikation und Dokumentation.
Lübeck: Verlag Schmidt-Römhild, ISBN: 3-7950-0740-2
Lehner, F.: Software-Dokumentation: Berlin: Logos Verlag, ISBN: 3-89722-211-6
Juhl, D.: Technische Dokumentation. Berlin, Heidelberg: Springer-Verlag,
ISBN 10 3-540-23813-1
Hoffmann, W.; Hölscher, B.G.; Thiele, U.: Handbuch für technische Autoren und Redakteure.
Erlangen: Publics Corporate Publishing), ISBN 3-89578-187-8
Berlin, Offenbach: VDE Verlag GmbH, ISBN 3-8007-2674-2
Förster, H.-P.: Texten wie ein Profi. Frankfurt am Main: F.A.Z.-Institut, ISBN 3-927282-90-1

– 68 – VDI 4500 Blatt 4 / Part 4