VDI 4500 Blatt-4 2011-12

VEREIN DEUTSCHER INGENIEURE y l h n c o s n t u a e d m r , e f r G u n w i t , n t f E a r 9 D 0 . 2 9 1 0 / : 2 e 1 b : a n g i o s i t u A d e e r r e e m h r ü r o F F

Dezember 2011 December 2011

VDI-RICHTLINIEN

ICS 01.110

VDI 4500

Technische Dokumentation Dokumentationsprozess Planen, Gestalten, Erstellen

Blatt 4 / Part 4

Technical documentation Documentation process Planning, layout, creation Die de deut sc sche Ve Vers io ion di di es eser Ri Ri ch cht lilinie is ist ve verbindlic h. h.

Inhalt

Ausg. deutsch/englisch Issue German/English

No guarantee c an an be gi gi ve ven wi wi th th re respec t to th the En Engl is ish tr transl aa- tion. The German version of this guideline shall be taken as authoritative.

Seite

Contents

Page

Vorbem orbemerkun erkungg . . . . . . . . . . . . . . . . . . .

2

Preliminary note . . . . . . . . . . . . . . . . . .

3

Einleitung Einle itung . . . . . . . . . . . . . . . . . . . . .

2

Introduct Intro duction ion . . . . . . . . . . . . . . . . . . . .

3

. . . . . . . . . . . . . 1.1 Ihr Nut Nutzen zen . . . . . . . . . . . . . . . . . 1.2 Was geh gehört ört zu zurr Technischen Te chnischen Dokumentation? . . . . . . .

4 4

1 Scope

. . . . . . . . . . . . . . . . . . . . . 1.1 Your benef benefit it . . . . . . . . . . . . . . . . 1.2 Wha Whatt cons constit titute utess technical documentation? . . . . . . . . .

5 5

1 An Anwe wend ndung ungsbe sbere reic ich h

2 Vom Produ Produktlebe ktlebenszyk nszyklus lus zum Dokumentationsprozess . . . . 3 Dok Dokume umenta ntatio tion n plan planen en .

. 3.1 Dok Dokume umente ntenar narten ten.. . . . 3.2 Pla Planun nungss gsschr chritt ittee . . . . 3.3 Dat Daten en auf aufber bereit eiten. en. . . .

. . . .

. . . .

. . . .

. . . . . . . . . . .

. . . .

. . . .

. . . . 4.1 Gru Grundsä ndsätze tze . . . . . . . . . . . 4.2 Layou Layout, t, Far Farbe, be, Text und Bild. . 4.3 Ausg Ausgabe abemed medium ium . . . . . . . .

. . . .

. . . .

12 12 12 24

3 Pla Planni nning ng of doc docume umenta ntatio tion n

. . . . . . . .

. . . . . . . .

. . . .

26 28 28 30

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . . . . . . . . .

. . . . . . .

. . . . . . . . Schwac Sch wachst hstell ellen enana analys lysee . . . . . . . Prüfung Prüf ungen en am Pro Produk duktt . . . . . . . Akzeptanz Akzep tanzunter untersuchu suchungen ngen . . . . . Anforderun Anford erungen gen an den den Techn Technisch ischen en Redakteur. Redak teur. . . . . . . . . . . . . .

. . . .

. . . .

5 Dok Dokume umenta ntatio tion n erste erstelle llen n.

5.1 5.2 5.3 5.4 5.5 5.6

. . Strukt Str ukturi uriere erenn . . . . . . . . Modular Modu larisi isiere erenn . . . . . . . Standa Sta ndardi rdisie sieren ren . . . . . . . Erstel Ers tellen len . . . . . . . . . . Endfa End fassu ssung ng . . . . . . . . . Dokume Dok umenta ntatio tionn anp anpass assen. en. .

6 Qua Qualit litäts ätsman manage agemen mentt

6.1 6.2 6.3 6.4

. . . . . . . . . . . . . .

. . . .

8

2 From the produ product ct lifecyc lifecycle le up to documentation process . . . . .

. . . .

4 Dok Dokume umenta ntatio tion n gestal gestalten ten

. . . .

6

. . . .

. . . .

. 13 . 13 . 13 . 25

4 Lay Layout out of of docum document entati ation on

. . . . . . . . . . . . . . . .

. 27 . 29 . 29 . 31

30 30 34 36 38 42 44

5 Cre Creati ation on of docu documen mentati tation on

. . . . . . . . . . . . . .

. . . .

46 48 54 54

6 Qu Qual alit ity y manag managem ement ent .

. . . .

56

. . . . . 4.1 Basic princ principles iples . . . . . . . . . 4.2 Layou Layout, t, Colou Colour, r, Text and Imag Imagee . 4.3 Out Output put me mediu dium m . . . . . . . . . 5.1 5.2 5.3 5.4 5.5 5.6 6.1 6.2 6.3 6.4

. . . . Structuring Struct uring . . . . . . . . . . . . Modular Modu larisi ising. ng. . . . . . . . . . . Standardisa Standa rdisation. tion. . . . . . . . . . Creati Cre ation on . . . . . . . . . . . . . Final versi version on . . . . . . . . . . . Adapting Adapt ing of docum documenta entation tion . . .

. . . .

. . . .

. . . .

9

. . . .

. . . .

. . 3.1 Doc Docume ument nt typ types es . . . . . . . 3.2 Pla Planni nning ng ste steps ps . . . . . . . . 3.3 Prepar Preparatio ationn of data. . . . . .

. . . . . .

7

. . . . . . .

. . 31 . . 31 . . 35 . . 37 . . 39 . . 43 . . 45

. . . . . . . . . . . . 47 Weak point anal analysis ysis . . . . . . . . . . . . 49 Acceptance Accep tance test testss with the produ product ct itsel itselff . . 55 Acceptance Accep tance test testss . . . . . . . . . . . . . . 55 Requireme Requi rements nts that the the technical technical writer writer must meet . . . . . . . . . . . . . . . . . 57

Glossar . . . . . . . . . . . . . . . . . . . . . . 60

Glossary . . . . . . . . . . . . . . . . . . . . . .

61

Schrifttum Schri fttum . . . . . . . . . . . . . . . . . . . . .

Bibliography.. . . . . . . . . . . . . . . . . . . . Bibliography

67

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 Vorgaben und Empfehlungen der Richtlinie Richtlinie VDI 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 Internet abrufbar unter www www.vdi.de/4500. .vdi.de/4500.

Einleitung

Die vorliege vorliegende nde Richtlinie Richtlinie VDI 4500 Blatt 4 behandelt behandelt Planung, Planung, Gestaltung Gestaltung und Erstellung im Dokumentationsprozess. Die folgende Übersicht zeigt Blatt 4 im Kontext Kontext der Richtlin Richtlinienrei ienreihe he VDI 4500.

–2–

B l a tt

In h a l te

Zielgruppe

Blatt 1: Begriffsdefinitionen und rechtliche Grundlagen

• Grundlage Grundlagenn der Techn Technisch ischen en Dokumentation • Dok Dokume umenta ntatitions onsarte artenn • rec rechtli htliche che For Forderung derungen, en, Rechtsnormen • Doku Dokument mentatio ationspf nspflich lichten ten • Ku Kunde ndenf nfor order derung ungen en • Pr Produ odukt ktleb lebens enszy zyklu kluss

• Geschäftsleiter Geschäftsleiter hinsicht hinsichtlich lich der Verantwortung und Haftung • Führ Führungs ungskräf kräfte te hinsichtl hinsichtlich ich des EinsatEinsatzes qualifizierten Personals und des Bereitstellens von Ressourcen • ausf ausführe ührende nde Pers Personen, onen, die die mit dem dem Erstellen Technischer Dokumentation beauftragt sind • externe Dienstleist Dienstleister, er, die eigenver eigenverantantwortlich Aufgaben übernehmen können

Blatt 2: Organisieren und Verwalten

• organisa organisatori torische sche Veran eranttwortung • Schn Schnitt ittstel stellen len zwis zwischen chen Verantwortungen • Pr Proje ojekt ktman manage agemen mentt • Frei reigab gabepr eproz ozedu eduren ren • Dat Datens ensic icher herung ung und und Archivierung


Blatt 3: Erstellen und Verteilen von elektronischen Ersatzteilinformationen

• Nutzer Nutzergru gruppe ppe und Anwendungsvorteile • Best Bestandt andteile eile und Real Realisie isie-rung eines elektronis elektronischen chen Ersatzteilkatalogs • Sc Schni hnitt ttste stelle llenn • Dat Datenaus enaustaus tausch, ch, Aus Austaus tauschchformate • Pra Praxisb xisbeisp eispiele iele,, Checklis Checklisten ten

• Führungs Führungs-- und Fachk Fachkräf räfte te von von Produktherstellern und -anwendern für Ersatzteildokumentation • externe Dienstleist Dienstleister, er, die eigenver eigenverantantwortlich Aufgaben übernehmen können

Blatt 4: Dokumentationsprozess: – Planen – Gestalten – Erstellen

• • • •

• Führungs Führungs-- und Fachkr Fachkräfte äfte,, die mit dem Erstellen Technischer Dokumentation beauftragt sind • externe Dienstleist Dienstleister, er, die eigenver eigenverantantwortlich Aufgaben übernehmen können • Pe Perso rsonen, nen, die die Informat Informatione ionenn für die Technische Dokumentation liefern

VDI 4500 Blatt 4 / Part 4

Ziel- und Benu ZielBenutze tzergrup rgruppen pen Baustein Baus teinee der Proz Prozessk esskett ettee Wer erkz kzeu euge ge Qualit Qua lität ätsma smanag nageme ement nt

Vorbemerkung

Vorbemerkung

Der Inhalt dieser Richtlinie ist entstanden unter Beachtung der Vorgaben Vorgaben und Empfehlungen der Richtlinie Richtlinie VDI 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 Internet abrufbar unter www www.vdi.de/4500. .vdi.de/4500.

Einleitung

Die vorliege vorliegende nde Richtlinie Richtlinie VDI 4500 Blatt 4 behandelt behandelt Planung, Planung, Gestaltung Gestaltung und Erstellung im Dokumentationsprozess. Die folgende Übersicht zeigt Blatt 4 im Kontext Kontext der Richtlin Richtlinienrei ienreihe he VDI 4500.

–2–

B l a tt

In h a l te

Zielgruppe

Blatt 1: Begriffsdefinitionen und rechtliche Grundlagen

• Grundlage Grundlagenn der Techn Technisch ischen en Dokumentation • Dok Dokume umenta ntatitions onsarte artenn • rec rechtli htliche che For Forderung derungen, en, Rechtsnormen • Doku Dokument mentatio ationspf nspflich lichten ten • Ku Kunde ndenf nfor order derung ungen en • Pr Produ odukt ktleb lebens enszy zyklu kluss


Blatt 2: Organisieren und Verwalten

• organisa organisatori torische sche Veran eranttwortung • Schn Schnitt ittstel stellen len zwis zwischen chen Verantwortungen • Pr Proje ojekt ktman manage agemen mentt • Frei reigab gabepr eproz ozedu eduren ren • Dat Datens ensic icher herung ung und und Archivierung


Blatt 3: Erstellen und Verteilen von elektronischen Ersatzteilinformationen

• Nutzer Nutzergru gruppe ppe und Anwendungsvorteile • Best Bestandt andteile eile und Real Realisie isie-rung eines elektronis elektronischen chen Ersatzteilkatalogs • Sc Schni hnitt ttste stelle llenn • Dat Datenaus enaustaus tausch, ch, Aus Austaus tauschchformate • Pra Praxisb xisbeisp eispiele iele,, Checklis Checklisten ten

• Führungs Führungs-- und Fachk Fachkräf räfte te von von Produktherstellern und -anwendern für Ersatzteildokumentation • externe Dienstleist Dienstleister, er, die eigenver eigenverantantwortlich Aufgaben übernehmen können

Blatt 4: Dokumentationsprozess: – Planen – Gestalten – Erstellen

• • • •

• Führungs Führungs-- und Fachkr Fachkräfte äfte,, die mit dem Erstellen Technischer Dokumentation beauftragt sind • externe Dienstleist Dienstleister, er, die eigenver eigenverantantwortlich Aufgaben übernehmen können • Pe Perso rsonen, nen, die die Informat Informatione ionenn für die Technische Dokumentation liefern


Ziel- und Benu ZielBenutze tzergrup rgruppen pen Baustein Baus teinee der Proz Prozessk esskett ettee Wer erkz kzeu euge ge Qualit Qua lität ätsma smanag nageme ement nt

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 (photocopying, 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-richtlinien.de). We wish to express our gratitude gr atitude 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 present guidelin guidelinee VDI 4500 Part 4 deals with with planning, planning, layout layout and creacreation in the documentation process. The following overview overview shows shows Part 4 in the context of the series of guidelines VDI 4500. Part

Contents

Target group

Part 1: Definitions and legal basics

• • • •

basic princip basic principles les of of techni technical cal docu do cume ment ntat atio ionn docume doc ument ntati ation on types types legal le gal requir requireme ement nts, s, legal standards • doc docume ument ntati ation on duties duties • cu custo stomer mer requir requireme ements nts • pr produ oduct ct lif lifec ecycl yclee

• managing managing directo directors rs in respect respect of responresponsibility and liability • seni senior or managers managers with respe respect ct to the the deployment of qualified personnel and the provision of resources • exe executives cutives who are assigned the task task of creating technical documentation • ex externa ternall service service providers providers,, who can disdischarge duties under their own responsibility

Part 2: Organisation and management

• organisa organisation tional al respons responsibil ibility ity • int interf erfaces aces betw between een respo responsinsibilities • pr proje oject ct mana managem gement ent • app appro rova vall proced procedur ures es • dat dataa protecti protection on and arch archivin ivingg

• managing managing direc director tor in in respect respect of responsibility and liability • seni senior or managers managers in respe respect ct of the the deploydeployment of qualified personnel and provision of resources • exe executives cutives who are assigned the task task of creating technical documentation • ex externa ternall service service provide providers, rs, who can discharge duties under their own responsibility

Part 3: Producing and distributing electronic spare parts information

• user grou groupp and adva advantag ntages es of • ex experts perts and and managem management ent of prod product uct use manufacturers and users for spare parts • comp componen onents ts and impl implement ementaadocumentation tion of an electronic spare • ex externa ternall service service pro provide viders, rs, who can parts catalogue assume tasks under their own responsi• in inte terf rfac aces es bility • dat dataa excha exchange, nge, exc exchange hange formats • pra practic ctical al examples examples,, checklis checklists ts

Part 4: Documentation process: – planning – layout – creation

• • • •

target targ et and and user user group groupss modules modu les of the the proce process ss chain chain tools qualility qua ty mana managem gement ent

• experts experts and manage management ment,, who are entrusted with the task of creating technical documentation • ex externa ternall service service provide providers, rs, who can assume duties under their own responsibility • pers persons ons who deliver deliver informat information ion for techtechnical documentation


–3–

Anwendungsbereich Ihr Nutzen

Blatt

Inhalte

Zielgruppe

Blatt 5: Dokumentationsprozess: Wirtschaftlich dokumentieren

• betriebswirtschaftliche Aspekte • Optimieren von Informationsund Dokumentationsprozessen • projektbezogene Kalkulation • Nutzen interner Ressourcen, Einbinden externer Dienstleister • Praxisbeispiele, Checklisten

• Geschäftsleiter hinsichtlich der Bewertung von Dokumentationsleistungen • kaufmännische Führungskräfte hinsichtlich der betriebswirtschaftlichen Bewertung • technische Führungskräfte hinsichtlich des Umsetzbarkeit mit vorhandenen oder zugekauften Ressourcen • Produktmanager oder Projektleiter hinsichtlich der kostengerechten Integration in den Produktlebenszyklus • ausführende Personen, die mit dem Erstellen und Koordinieren Technischer Dokumentation beauftragt sind

Blatt 6: Dokumentationsprozess: Publizieren

• Publizieren als Teil des Dokumentationsprozesses • rechtliche Aspekte • Informationszugriff, Schnittstellen und Standards • Technologien und Systeme • Qualitätsmanagement • Praxisbeispiele, Checklisten

• Verantwortliche, die für die datentechnische Infrastruktur, die Dokumentation und die Verteilung der Dokumente verantwortlich sind • Führungs- und Fachkräfte, die Software für den Publikationsprozess auswählen oder selbst erstellen • externe Dienstleister, die eigenverantwortlich Aufgaben übernehmen können

Als eine Ergänzung zu den einschlägigen Normen zeichnet sich diese Richtlinie dadurch aus, dass die genannten Aspekte streng prozessorientiert zu interpretieren sind. Beim Leser wird ein entsprechendes Abstraktionsvermögen vorausgesetzt, damit er die Sachverhalte und Beispiele auf sein eigenes Arbeitsgebiet anwenden kann. Insbesondere muss er die Auswahl der für seine Aufgabe und Situation anwendbaren Dokumente im Einzelfall selbst bestimmen. Ziel der Richtlinie VDI 4500 Blatt 4 ist nicht die Vollständigkeit der Normenverweise und anderer Ausführungsdetails, stattdessen steht die Prozessbetrachtung im Vordergrund.

Der Prozess steht 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, gelten auch für die Schritte Planen, Gestalten und Erstellen im Dokumentationsprozess.

1 Anwendungsbereich

Die Inhalte der Richtlinie VDI 4500 Blatt 4 wenden sich an die Ersteller von Technischer Dokumentation und besonders an die Zielgruppe der Technischen Redakteure, die im klassischen Sinn Externe Technische Dokumentation erstellen. 1.1

Ihr Nutzen

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


Scope Your benefit

Part

Contents

Target group

Part 5: Documentation process: economical documentation

• business managerial aspects • optimising of information • and documentation processes • project-based calculation • use of internal resources, inclusion of external service providers • practical examples, checklists

• managing directors in terms of evaluation of documentation services • commercial managers in terms of business managerial evaluation • technical managers in terms of practicability with available or purchased resources • product manager or project manager with respect to cost-efficient integration in the product lifecycle • executives who are entrusted with the creation and coordination of technical documentation

Part 6: Documentation process: publication

• publishing as part of the documentation process • legal aspects • access to information, interfaces and standards • technologies and systems • quality management • practical examples, checklists

• responsible persons who are in charge of the data infrastructure, the documentation and the distribution of the documents • experts and management, who select or themselves create software for the publication process • external service providers, who can assume duties under their own responsibility

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 processoriented 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 particular, he must himself determine the selection of the documents applicable to his task and situation in the individual case. Aim of the guideline VDI 4500 Part 4 is not the completeness of the references to standards and other layout details; the focus is rather on the process examination.

The process is at the forefront

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 prerequisites 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 writers, 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 Erstellen von Technischer Dokumentation als Teilprozess im Dokumentationsprozess. In der Zielgruppe von Blatt 4 sind in erster Linie Personen, die innerhalb dieses Prozesses die Technische Dokumentation erstellen, aber auch diejenigen, die Informationen für die Technische Dokumentation liefern oder Teildokumente beistellen. In jeder Phase des Produktlebenszyklus entsteht Interne Technische Dokumentation. Sie verhindert, dass erworbenes Wissen verloren geht und ist gleichzeitig auch der geforderte aussagefähige Nachweis des Produktherstellers 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.

Interne Technische Dokumentation

Das Benutzen eines Redaktionshandbuchs ermöglicht eine systematische Erstellung von Externer Technischer Dokumentation. Dadurch werden die Dokumentationsprozesse transparent, das Erstellen von Technischer Dokumentation wird effizient, und die Dokumente lassen sich in ihrer Qualität verbessern. Die Richtlinienreihe VDI 4500 ist eine allgemein anerkannte Regel der Technik, die wertvolle Hilfestellung und praxisnahe Empfehlungen für das Planen, Erstellen und Gestalten von Technischer Dokumentation gibt.

Anerkannte Regel der Technik

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. Bil d 1 zeigt den Bereich der Technischen Dokumentation und seine Unterteilung in Interne Technische Dokumentation und Externe Technische Dokumentation. In den beiden Bereichen der Technischen Dokumentation sind unterschiedliche Aspekte zu dokumentieren: • Die Interne Technische Dokumentation muss sämtliche Produktentwicklungsschritte als Nachweis transparent, reproduzierbar und nachvollziehbar festhalten – von der Produktanalyse bis hin zu den Entsorgungsprozessen. • Die Externe Technische Dokumentation dient der Produktnutzung durch den Anwender. Die Dokumentenarten und Dokumentationsprozesse können vielfältig sein. Marketingunterlagen müssen ebenfalls in die Dokumentationsprozesse mit einbezogen werden. Prozessabweichungen

–6–


Blatt 4 unterscheidet nur dann zwischen Interner Technischer Dokumentation und Externer Technischer Dokumentation, wenn die Prozesse voneinander abweichen.

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 information for the technical documentation or provide portions of the documents. In each phase of the product lifecycle, internal technical documentation is created. It prevents acquired knowhow from being lost and is, at the same time, also the required informative proof by the product manufacturer regarding the fulfilment of the requirements arising from various legal areas. Internal technical documentation forms the basis for the external technical documentation which builds upon it.

Internal technical documentation

The use of an editorial manual allows for systematic creation of external technical documentation. This makes the documentation process transparent, the creation of technical documentation becomes more efficient and the quality of the documents can be improved. The series of guidelines VDI 4500 is a generally acknowledged rule of technology, which provides valuable help and practical re commendations for the planning, creation and layout of technical documentation.

Acknowledged rules of technology

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. Fig ur e 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 retraceable – 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 diverse. Marketing documents must be likewise included in the documentation processes. Process deviations

Part 4 distinguishes between internal technical documentation and external technical documentation only if the processes deviate from each other.


–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 Technischen Dokumentation oder beeinflussen sie (siehe Bild 2). Beispiele von Dokumentenarten finden sich in VDI 4500 Blatt 1. Weiterführende Informationen zum Lebenszyklusmodell sind in DIN ISO 15226 zusammengefasst.

–8–


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 influence it (see F igu re 2). Examples of document types are given in VDI 4500 Part 1. Continuative information about lifecycle model is summarised in DIN ISO 15226.


–9–

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

Bild 2. Typische Dokumente/Dokumentationsprozesse im Rahmen des Produktlebenszyklus

– 10 –


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


– 11 –

Dokumentation planen Dokumentenarten

3 Dokumentation planen

Zur Sicherung der Qualität und zur Erhöhung der Wirtschaftlichkeit empfiehlt sich eine mit dem Produktlebenszyklus abgestimmte Planung der Technischen Dokumentation. Die Planung hängt sehr stark von den unternehmens- und produktspezifischen Prozessen ab. Deshalb können die nachfolgend genannten Planungsschritte 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 Dokumentenart. Der Produktlebenszyklus beginnt mit der Produktidee und endet mit der Wiederverwertung 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 Verwendung 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 Technische Dokumentation). Siehe dazu auch Richtlinie VDI 4500 Blatt 1, Tabelle 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 Folgenden beispielhaft einige herausgegriffen und beschrieben. Verantwortlichkeiten

Analysen

Das Unternehmen muss durch interne Verfahrensfestlegungen (z.B. Redaktionshandbuch, 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. Eine rechtlich einwandfreie und anwendergerechte Technische Dokumentation setzt voraus, dass • die Zielgruppen bekannt sind, • das Produkt analysiert wird, • die Maßnahmen aus Risikoanalyse und Risikobewertung in Produktentwicklung und -dokumentation umgesetzt sind, • die einschlägigen Normen aus der Normenrecherche in Produktentwicklung und -dokumentation beachtet werden und • die einschlägigen Rechtsvorschriften, insbesondere aus dem Produktsicherheitsrecht, beachtet werden.

– 12 –


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 processes. 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 representative samples of the multiplicity of possible planning steps. Responsibilities

Analyses

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 documentation. Likewise, it must be specified as to how the documents shall be made available in sufficient quality and on time for the subsequent documentation processes. 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 implemented 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 –


Planning of documentation Planning steps

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


– 15 –


Welche Abteilungen oder welche Personen innerhalb der Betriebsorganisation 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 Aufbauorganisation ab. Einen beispielhaften Überblick über Zulieferungen aus Produktmanagement und Produktentwicklung als Voraussetzung für eine fachgerechte Technische Dokumentation gibt Bi ld 4.

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

Ablaufplanung

Unabhängig von der Dokumentenart und vom Produkt folgt der Dokumentationsprozess innerhalb der Technischen Redaktion bestimmten Abläufen, wie in B il d 5 beispielhaft dargestellt (gezeigt sind nur die wesentlichen Phasen): Diese Prozessschritte begleiten das Produkt über den gesamten Produktlebenszyklus und stellen einen kontinuierlichen Iterationsprozess dar, der die Fortentwicklung des Produkts selbst sowie die Veränderungen aller Randbedingungen widerspiegelt. Freigegebene Fassungen sind so zu archivieren, dass der Hersteller anhand der Dokumente den Nachweis der Sorgfaltspflicht jederzeit während des Produktlebenszyklus erbringen kann.

– 16 –



Which departments or which persons within the plant organisation of a company 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 documentation is given in Fig ur e 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 sequences, as represented by way of example in F ig ure 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 –


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

Zielgruppenanalyse

– 18 –

Die Zielgruppenanalyse ist vom Hersteller durchzuführen und zu dokumentieren. 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 Dokumentation 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?


Alle Rechte vorbehalten © Verein Deutscher Ingenieure e.V., Düsseldorf 2011


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


– 19 –


• 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 Zielgruppenanalyse haben sich zwei Methoden bewährt: Wer-macht-was-Matrix und Persona-Methode.

Wer-macht-was-Matrix

Es ist zweckmäßig, sich zunächst einen Gesamtüberblick über Nutzer, Dokumentenarten und Handlungen mittels der Wer-macht-was-Matrix zu verschaffen. Die Persona-Methode kann anschließend den Technischen Redakteur dabei 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. Die Methode der Wer-macht-was-Matrix führt zu einer Klassifikation der Nutzer hinsichtlich ihrer Tätigkeiten und typischen Erfahrungen mit dem betreffenden Produkt. Dazu werden die durchzuführenden Tätigkeiten über den gesamten Produktlebenszyklus erfasst und den typischen Ausführenden zugeordnet. 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. Tab ell e 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

– 20 –

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



• Under which conditions and in which situation are the product and the respective 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 .

Who-makes-what matrix

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 subsequently be used to support the technical writers in structuring, content writing 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. 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 users and the resultant classification of the documents. Tab le 1 shows in a simplified form, using a concrete example, that the factual 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 im portant 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 –


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

Bediener Fachausgabe

Wartungstechniker

Parameter für OCR einstellen

X („Fine tuning“)

Vorbeugende Instandhaltung

X (tägliche Wartungsarbeiten)

X (Reparaturen, Kundendienst)

Steuerkonsole bedienen

X (bedienen)

X (Fehler prüfen)

Fehler im Brieflauf beheben

X (im Magazinbereich)

Briefe in Standardbehälter füllen Briefe in Magazin einfüllen

Konfigurationstechniker

X (Grundkonfiguration)

X (Tastenzuordnung definieren)

X (im Ausgabefachbereich) X (im Ausgabefachbereich)

X (im Magazinbereich)

Der Vorteil eines solchen detaillierten Benutzerprofils ist, dass dieser idealtypische Benutzer, dem man sogar einen Namen zuordnet, vor dem geistigen Auge des Technischen Redakteurs so visualisiert wird, dass er nicht mehr anonym in der abstrakten Benutzerzielgruppe untergeht. Es entsteht eine nahezu persönliche Beziehung zwischen dem imaginären Benutzer und dem Technischen Redakteur. Vorgaben und Forderungen

Alle produktspezifischen und anwendungsbezogenen Forderungen an die Technische Dokumentation aus Gesetzen, Verordnungen, Vorschriften, technischen Normen, Richtlinien, aber auch aus Verträgen müssen vollständig recherchiert und erfasst werden. Neben direkten Anforderungen von Normen an die Externe Technische Dokumentation sind darüber hinaus auch Informationen aus produktspezifischen 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 Dokumentation und benennen unter anderem die Zielgruppen für die jeweiligen Dokumente.

Risikoanalyse und Risikobewertung

Produktanalyse

Es empfiehlt sich, alle rechtlichen, technischen und vertraglichen Forderungen – nach Prioritäten geordnet – in Checklisten aufzuführen. Durch Risikoanalyse und Risikobewertung werden die Restrisiken ermittelt, 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 (unmittelbare und mittelbare Sicherheitstechnik) und organisatorische Maßnahmen nicht auszuschließen sind. Die Informationen über Restgefahren fließen unmittelbar in die Externe Technische Dokumentation ein. Die Externe Technische Dokumentation darf nicht dazu missbraucht werden, entwicklungstechnische 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. 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 –



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

User of collection tray

Customer engineer

Setting the parameters for OCR

X (“fine tuning”

Preventive maintenance

X (daily maintenance jobs)

X (repair, customer service)

Using the control panel

X (using)

X (checking errors)

Repairing the error in letter run

X (in the magazine area)

Filling the letters in standard containers Filling the letters in the magazine

Configuration engineer

X (basic configuration)

X (defining the key assignments)

X (in the collection tray area) X (in the collection tray area)

X (in the magazine area)

The advantage of such a detailed user profile is that this ideal type use r, 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 requirements

All product-specific and use-oriented requirements on technical documentation 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 product specifications, as a rule, contain requirements on technical documentation and name, among other things, the target group for the respective documents.

Risk analysis and risk estimation

Product analysis

It is recommended to list all the legal, technical and contractual requirements – according to priorities – in checklists. Risk analysis and risk estimation serve to determine residual risks, that are present for a specific activity on or with a product after the application of protective 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 design and development. Hazards and risks are, for instance, identified and/or evaluated by the engineer of the machine in case of products that are subject to the European Machinery Directive (2006/42/EC). The product analysis delivers the requirements in terms of content of the technical documentation so that the user can use the product effic iently. 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, Entwicklung, Konstruktion, Vertrieb, Qualitätssicherung und Kundendienst zur Verfü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/Anwendergruppen und • Kundendienst- und Serviceberichten. 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

Informationsverwaltung planen

3.3

Daten aufbereiten

Aus der Vielzahl der gewonnenen Daten müssen die für die Zielgruppen und Dokumentationsarten erforderlichen Informationen ausgewählt und aufbereitet werden. Informationsquellen für Technische Dokumentation sind z.B. technische Unterlagen, Protokolle, Verträge und Notizen genauso wie E-Mails. Informationen werden aber auch durch Gespräche übermittelt.

Quellen

Als Vorarbeit für Gespräche ist es sinnvoll, einen detaillierten Rechercheplan auszuarbeiten und sich bewährter Methoden- und Fragetechniken zu bedienen. 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 Papierversion und elektronischer Form vorliegen. Informationen vereinheitlichen

– 24 –

Aus der Unterschiedlichkeit der Quellen und der Archivierung heraus entsteht die Notwendigkeit, Daten und Dokumente zu prüfen, zu selektieren und zu sichern. Die Informationen sollten hinsichtlich Inhalt und Format strukturiert und vereinheitlicht werden. Abhängig von der anschließenden Art der Nutzung kann die Aufbereitung erheblichen Aufwand bedeuten. Zum Beispiel erfordert die Ablage in relationalen Datenbanken das Umsetzen der Da-


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, development, 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. Before and during the product lifecycle, a multiplicity of data and information 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

Planning of information management

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 documents, records, contracts and notes as well as e-mails. Information is, however, 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 formats. Thus, documents from the development department vary from documents 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 format 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 zugeordnet 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 Datenbestände und der Einsatz unterschiedlichster EDV-Systeme produzieren eine Vielzahl unterschiedlicher Datenformate. Auch hier sind die Vereinheitlichung der Datenbestände und die Konzentration auf wenige, universell verwendbare Formate oberstes Gebot. Standardisierte Prozesse, Dokumente und Daten!

Wichtig zum Einsatz aller nachfolgenden Techniken sind immer standardisierte 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 Entscheidung 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 Gestaltungselementen 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 Schwerpunkte vorgestellt, die bei der Festlegung der Gestaltung von Externer Technischer Dokumentation zu berücksichtigen sind. Die Einsatzmöglichkeiten und ihre Wirkung sind in der einschlägigen Fachliteratur ausführlich behandelt. Auf Ausführungsdetails wird daher in dieser Richtlinie nicht speziell eingegangen. – 26 –


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 ba ses and concentration on a few, universally applicable formats is of paramount importance. Standardised processes, documents and data!

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

Only after the structuring of documents and data with the aim of a standardised 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 decision 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 consistently grown in parallel to this development. In standards, fundamental approaches 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 requirements related to practical and legal aspects, can be fulfilled. This guideline introduces the focuses that must be considered while specifying the layout of external technical documentation. The usage options and their effects are treated in detail in the pertinent technical literature. Therefore, layout details are not dealt with especially in this guideline.


– 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 Informationen. Das Gestaltungskonzept fußt auf den Ergebnissen der Produkt- und Zielgruppenanalyse, die im Idealfall auch Aussagen zur mentalen Situation und zu den Umgebungsbedingungen des Nutzers sowie zu der Bedeutung von Gestaltungselementen 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 grundlegender Bedeutung sind Wahrnehmung und Verständlichkeit von Texten und Abbildungen. Produktgröße und Platzverhältnisse sind zu berücksichtigen, wenn die Externe Technische Dokumentation direkt auf dem Produkt angebracht werden muss. Sie muss anwendungsbezogen für die gesamte Nutzungsdauer verfügbar bleiben. Die Gestaltungsrichtlinien müssen – je nach Einbindung externer Stellen – in jeweils aktueller Form an externe Dienstleister, Übersetzer und Bauteillieferanten weitergeleitet werden. Sie dürfen keinen Spielraum für individuelle Gestaltung lassen. Aber auch im Unternehmen sind die Gestaltungsrichtlinien zwingend zu berücksichtigen; sie können in Form von Redaktionshandbü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

– 28 –

Layout, Farbe, Text und Bild

Die Text- und Bildgestaltung prägt wesentlich die optische S truktur eines Dokuments. Sie wird durch das Layout festgelegt. Im Allgemeinen sind das Layout eines Dokuments und das Layout seiner einzelnen Seiten unterschiedlich. Die optische Strukturierung ist Orientierungshilfe, z.B. durch Register, Inhalts- und Stichwortverzeichnisse. Elemente wie Format, Überschriften, A bsä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. Generell sollen sich Text und Bild gegenseitig unterstützen. Dies kommt auc h den Wahrnehmungsfähigkeiten des Menschen zugute, der dann eine besonders gute Aufnahmefähigkeit von Informationen zeigt, wenn sich visuelle Elemente und textliche Anleitungen ergänzen. 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 Bildschirmanwendungen sowie durch die Fortentwicklungen im Reproduktionsbereich Medien (z.B. kostengünstige Farbdrucker am Arbeitsplatz) hat sich die Verwendung von farbigen Gestaltungsmerkmalen in vielen Bereichen bereits durchgesetzt. 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 mental state and the environmental conditions of the user as well as about the significance 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 correctly ascertainable. A clear and logical structuring of the content is illustrated creatively through optical structural devices. Of fundamental importance are perception and comprehension of texts and illustrations. Product size and space ratios must be taken into account, if the external technical documentation has to be applied directly on the product. It must be useoriented 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 layout. 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 design. 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 genera l, the layout of a document 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 accurately through an illustration than through text alone. In general, text and image 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 documentation. 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 reproduction segment of media (e.g. cost-effective colour printer at workplace), the use of colour design features has caught on in many areas.


– 29 –

Dokumentation erstellen Ausgabemedium

Für die textliche Gestaltung sind zum einen das äußerliche formale Erscheinungsbild und zum anderen die inhaltliche sprachliche Gestaltung festzulegen.

Text

Die inhaltliche Gliederung orientiert sich am Zweck der Externen Technischen Dokumentation und hat demnach den Blickwinkel auf das Produkt, a uf eine zu lösende Aufgabe oder die Abfolge der Lernschritte des Nutzers gerichtet. Bei sensiblen Textarten (z.B. Sicherheitshinweise) ist auf eine konsistente Formulierung besonders zu achten. Als wichtige Verständnishilfen müssen Bilder in der Technischen Dokumentation deutlich und eindeutig sein und sich auf das Wesentliche beschränken. Sie müssen den Text in jedem Fall ergänzen und, dem Handlungsablauf entsprechend, im Text logisch eingebunden sein.

Bild

Als Bilder gelten Diagramme ebenso wie Piktogramme, Symbole, Illustrationen und Fotos. Zutreffende Normenwerke, der Informationszweck und die Zielgruppe bestimmen in erster Linie, in welcher Art eine Information visualisiert werden soll. Im Hinblick auf notwendige Übersetzungen sollten Bilder keinen Text enthalten. 4.3

Ausgabemedium

Von erheblicher Bedeutung ist die rechtzeitige Auswahl der späteren Medien zum Verteilen und zum Gebrauch. Die Gestaltungsregeln für die Ausgabemedien 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 Lesbarkeit 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 vorgesehen ist (Cross-Media-Publishing).

5 Dokumentation erstellen

Die Inhalte dieses Abschnitts beziehen sich hauptsächlich auf Externe Technische Dokumentation. Es spricht jedoch nichts dagegen, die nachfolgend empfohlenen Methoden auf die Interne Technische Dokumentation anzuwenden. Es wird ein Ablauf nach B il d 6 empfohlen, der systematisch von der Zusammenstellung der notwendigen Informationen für eine Dokumentation hin zum Erstellungsprozess mit Texten und Visualisierungsmitteln führt. 5.1

Strukturieren: Informationsauswahl treffen, Strukturkonzept definieren, Gliederung festlegen

– 30 –

Strukturieren

Um die Auswahl der Dokumenttypen zu definieren und für jedes Dokument den Aufbau und die innere Gliederung festzulegen, sind folgende Eingangsinformationen wichtig: • zutreffendes Normenwerk • Qualitätsanforderungen


Creation of documentation Structuring

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

Text

Content structuring is oriented to the purpose of the external technical documentation and, therefore, has its sights set on the product, on a task to be resolved 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. 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.

Image

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 distribution 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 monitor. Furthermore, reading of hard copy is perceived as less strenuous, and the reader can reproduce more from what he has read. The evaluation of readability 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 tec hnical 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 Fig ur e 6, which systematically leads from the compilation of the necessary information for documentation up to the creation process with text and visualisation means. 5.1

Structuring: information selection, defining the structural concept, specifying the organisation and arrangement

Structuring

In order to define the selection of document types and to specify the structure and the internal arrangement for each document, the following input information is important: • 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 Dokumentation Auf Basis dieser Eingangsinformationen ergibt sich nahezu zwangsläufig die Definition von Dokumententypen sowie die Dokumentenstruktur der Einzeldokumente. Zum inneren Aufbau geben die einschlägigen Normen und EURichtlinien mit Verweisen auf die Benutzerinformation wichtige Hinweise, die unbedingt zu befolgen sind.

Empfehlungen für den Zielgruppenbezug

– 32 –

Die Vorgehensweise der Strukturierung lässt sich in folgende beispielhafte Schritte gliedern: a) gesammelte Informationen aus Recherchen, Analysen und Vorgaben benennen b) erforderliche und gewünschte Informationen für die Dokumentation auswä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. Informationen für unterschiedliche Zielgruppen sollten in getrennten Dokumenten 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 Ausführung durch Laien zu verhindern. Dazu ist die jeweilige Zielgruppe eindeutig zu definieren.


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 individual 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 instructions 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 specifications b) selecting the necessary and desired information for the documentation

Recommendations for target group reference

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. Information for different target groups should be composed in separate documents 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 prevent 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 anzugeben. 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 dokumentieren. 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-Konzept des Herstellers/Lieferanten.

Inhalt

5.2

Modularisieren

Aus folgenden Gründen sollte der modulare Aufbau einer Dokumentation im Prozess verankert werden: a) Die Modularisierung von Dokumentationsinhalten gemäß dem technischen Aufbau des Produkts und den jeweils zuzuordnenden Nutzerinformationen vereinfacht den Entstehungsprozess der Dokumentation. b) Ein baugruppen- oder komponentenbezogener Aufbau der Dokumentationsinhalte begünstigt die Dokumentation von Produktvarianten. c) Wiederholt nutzbare Inhalte, die in mehreren Dokumentenstrukturen verwendet 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 unabhä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 Gesamtdokumentation aus zentral verwalteten Modulen einrichten

Bild 7. Aufbau verschiedener Dokumente (hier: Einführung, Bedienung, Wartung) aus mehrfach verwendbaren Modulen eines zentralen Bausteinpools, der auch unterschiedliche Produktvarianten bedienen kann

Das Ergebnis eines solchen Ablaufs sind einzelne Informationsmodule mit eindeutig zugeordneten Objekteigenschaften (Metadaten). Diese Module – 34 –


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 and depth of description of the various documents result from the results of the preceding analyses. Minimum specifications from the laws, regulations, 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 pr oduct. The depth of description is oriented to the need for explanation of the product and to the after-sales concept of the manufacturer/supplier.

Content

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 document structures, reduce the effort for the creation, proofreading and updating of documentation. The following sequences are recommended: a) fragmentation (“granulation”) of the entire documentation into convenient, 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 documentation 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 information modules with explicitly assigned object properties (me tadata). These VDI 4500 Blatt 4 / Part 4

– 35 –

Dokumentation erstellen Standardisieren

können unabhängig voneinander – auch durch verschiedene Mitarbeiter – erstellt und lektoriert werden. • 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 unerwü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)?

Empfehlungen

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:

Redaktionshandbuch als Hilfsmittel für konsistente Standardisierung

• dokument- und produktbezogene Gliederungsstrukturen • Visualisierungsmittel • Sprache und deren Gebrauch • Gestaltungsvorgaben • Publikationsprozesse und Medien • Datei- und Austauschformate • Arbeitsorganisation In Style-Guides, Corporate-Design-Leitfäden, Qualitätsmanagement-Handbüchern und Redaktionshandbüchern werden die unternehmensbezogenenen und produktbezogenen Standardisierungsziele und -mittel dokumentiert und verbindlich vorgegeben. Das Redaktionshandbuch definiert den gesamten Workflow im Dokumentationsbereich 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 –


Creation of documentation Standardisation

modules can be created and proof-read independent of each other – even by different colleagues. • Modularisation is a basic prerequisite for the processing of technical documentation in so-called content management systems. Even for the creation 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 economically: 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 undesired. • 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)?

Recommendations

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 reduction of costs. Standardised can be:

Editorial manual as aid for consistent standardisation

• document-based and product-based structuring • visualisation means • language and its use • layout specifications • publication processes and media • file and exchange formats • work organisation In style guides, corporate design guidelines, quality management manuals 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 forward at least the pertinent chapters to all the offices involved in the documenVDI 4500 Blatt 4 / Part 4

– 37 –

Dokumentation erstellen Erstellen

Kapitel weiterzugeben. Das betrifft auch Dienstleister wie freie Technische Redakteure oder Übersetzer.

5.4

Zielgruppengerecht formulieren

Erstellen

Dieser Abschnitt befasst sich hauptsächlich mit der Umsetzung der strukturierten, 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 Medieneinsatz: So gelten besondere Regeln für gesprochenen Text in MultimediaAnleitungen oder übersetzungsfreundliche Texte in Printanleitungen. In jedem Fall aber gelten für den Verfasser Technischer Dokumentation besondere Regeln, die sich nicht notwendigerweise an den in der Schule gelernten 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 nachhaltige Erinnerung sein. In der Technischen Dokumentation sind Wortwiederholungen kein Zeichen für schlechtes Deutsch, sondern im Gegenteil erwünscht, um eindeutiges Verstä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. Natürliche Sprachen werden als von Menschen gesprochene Sprachen beschrieben, die historisch gewachsen sind, wie Deutsch, Englisch, Französisch usw. Sie enthalten neben einer Vielzahl von Regeln nahezu unzählige Ausnahmen und Uneindeutigkeiten. Trotzdem kommt keine Darstellungsart in der Technischen Dokumentation ohne natürliche Sprache aus.

Sprachen

Künstliche Sprachen wurden für ganz bestimmte Zwecke neu konstruiert, oft von nur einigen Personen oder einer Gruppe. Zwei der bekanntesten Kategorien dieser Sprachen sind:

Grundregeln für verständliche Texte

• Plansprachen, um die internationale Verständigung zwischen verschiedenen 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 angemessen ausgerichtet und deshalb für diese nicht unmittelbar verständlich sind. Einige Grundregeln führen zu verständlichen und eindeutig zu übersetzenden Texten: • kurze Sätze, einfacher Satzaufbau • Fachbegriffe sind beim ersten Vorkommen oder in einem Glossar zu erlä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örter/Wendungen, die z.B. für Handlungsanweisungen verwendet werden, sollten einheitlich sein.

– 38 –


Creation of documentation Creation

tation process. This equally includes service providers such as self-employed technical writers or translators.

5.4

Target group oriented formulation

Languages

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 communication channels – for example textless pictorial instructions – ar e comparatively less widespread in the area of technical documentation. To be distinguished are various text types for diverse m edia use: Thus, special rules apply for spoken text in multimedia instructions or translation-friendly texts in print instructions. In any case, however, the composer of technical documentation is subject to 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 language, 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 understands the word unambiguously. Simple language is also required because the unambiguity of the source language is therewith achieved for the translation process. Natural languages are described as languages spoken by man, which have evolved historically, such as German, English, French, etc. In addition to a variety of rules, they contain innumerable exceptions and ambiguities. Nevertheless, 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 languages are:

Basic rules for comprehensible texts

• 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 adequately adapted to the average level of knowledge and experiences of the target group and are therefore not directly comprehensible for these users. A few 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 develop a terminology at the time of composing the text, so that uniform use of terms, phrases, etc. is ensured. Terminology should not consider technical terms alone. Even terms/words/phrases, which are, for instance, used for describing actions, should be uniform.


– 39 –

Dokumentation erstellen Erstellen

Ergebnisse anwendungsspezifischer Produktbeobachtungen über angemessen 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 Anwendung in den USA oder in Schwellen-/Entwicklungsländern) sind zu berü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öglichkeiten für gefährlichen Miss- oder Fehlgebrauch entstehen können. Übersetzung ist die möglichst genaue Übertragung eines Texts in eine Fremdsprache, 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 festzulegen und mit dem Übersetzer die Einhaltung verbindlich zu vereinbaren, • die elektronischen Formate von Quelltext und Zieldokument sowie die zugelassenen Übersetzungswerkzeuge vorzuschreiben, • Prüfroutinen für die Übersetzungen vorzusehen, • für die Abwicklung von Übersetzungsaufträgen die Vorgaben der einschlägigen Normen zu vereinbaren.

Übersetzung

Lokalisierung

Grundsätzlich sollten fremdsprachige Technische Dokumentationen durch fachkundige Mitarbeiter im Verwenderland/Einsatzland geprüft werden. Bei Übersetzungen sind grundsätzlich Bräuche und Gewohnheiten sowie der normale Ausbildungsstand im Zielland zu berücksichtigen. Dabei wird es zumeist 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, Richtlinien 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 Zusammenhänge beschreiben, die sprachlich oder logisch nur schwer zu formulieren 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 Wahrnehmungsforschung und die Entwicklung der technischen Möglichkeiten der Visualisierungsmittel zu beobachten. Manche bewährten Methoden zur Erstellung von Visualisierungselementen werden durch neue wirtschaftlichere Methoden ersetzt. So lassen sich beispielsweise aufwendig zu erstellende Dokumentationsfotos durch fotorealistische Computergrafik ersetzen, die unmittelbar mit entsprechenden Programmen aus den häufig im Konstruktionsbereich einge-

– 40 –


Creation of documentation Creation

Results of use-oriented product monitoring over adequately long periods deliver the yardstick for the necessity of the use of warning notes and definitions of use contrary to the intended purpose or misuse.

Translation

Localisation

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 differences. Selective individual notes must be additionally repeated at places, where there might be cause for or the potential of hazardous misuse or incorrect use. 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 translation-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. 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 becomes mostly necessary that the translator adapts formulations to the local conditions. At the same time, his degree of freedom must be clarified contractually 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 country 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 illustration (picture or series of pictures). In technical documentation, which describes abstract data and complex contexts, which are difficult to formulate linguistically or logically, it is imperative to add visualisation to the linguistic content and to therewith make them better understandable. A relatively large proportion of pictures increases comprehension and the attractiveness and furthermore improves reading pleasure. It must be weighed on a case-by-case basis as to which type of visual implementation 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 visualisation elements are being replaced by newer, more economical methods. Thus, for instance, the laborious process of documentation photos can be replaced 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. Bei der Verwendung von Farben ist auf die unterschiedliche Bedeutung von Farben in den verschiedenen Kulturkreisen zu achten.

Bedeutung von Farben

5.5

Endfassung

Während des Erstellungsprozesses und danach sind verschiedene Anforderungen 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 Spezifikation der Lebensdauer aller Dokumente, die für den Nachweis der Sorgfaltspflicht des Herstellers gefordert sind, und der Externen Technischen Dokumentation. Die notwendigerweise zu überschreitende Lebensdauer liegt bei Konsumgütern im Bereich weniger Jahre bis Jahrzehnte, bei langlebigen Investitionsgütern bis zur Beendigung des Produktlebenszyklus teilweise über 100 Jahre. Danach richtet sich die Auswahl von Betriebssystemen und Anwendersoftware 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 Dokumentenzusammenstellung unabdinglich. Merke: Ein von der Investition her scheinbar preisgünstiges Dokumentationskonzept kann hohe Folgekosten und Aufwendungen beim täglichen Umgang nach sich ziehen.

Dokumentationssoftware

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 Interne Technische Dokumentation zum späteren Nachweis der Erfüllung der Sorgfaltspflichten des Herstellers archiviert werden. Die Aufbewahrungsfristen 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 Datenaustauschformate 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ünftig Alternativen bereit. – 42 –


Creation of documentation Final version

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

Significance of colours

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 manufacturer and of the external technical documentation. The life time that must necessarily be exceeded is in the range of a few years to decades in case of consumer 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 software 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 software operation, file storage and document compilation is indispensible for such periods. Note: An apparently lowest priced documentation concept from the point of

Documentation software

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 considers 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, transferability to various operating systems, processing for printing and the distribution 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 archiving), 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.


– 43 –

Dokumentation erstellen Dokumentation anpassen

• Verwenden herstellerunabhängiger Dokumentenstandards konform zu den Regelwerken XML oder SGML als gemeinsame Basis offener und unterschiedlicher Publishing-Systeme. Dadurch können einmal festgelegte Dokumentengerüste von unabhängig arbeitenden Dokumentationsteams mit Inhalten ausgefüllt werden. Für die Publikation in unterschiedlichen Medien sind zu den Grunddaten entsprechende Verarbeitungswerkzeuge nötig, damit aus den Grunddaten z.B. HTML, PDF oder andere Formate erzeugt werden können. Für den Austausch der XML- oder SGML-Daten zwischen verschiedenen Applikationen müssen entsprechende Schnittstellenkonverter bereitgestellt werden, die die verschiedenen Dokumentstrukturen und Layoutvorgaben vom Quell- zum Zielprogramm überführen. • Beim Festlegen der Datenaustauschformate muss die Definition langlebiger Datenträger und Übertragungsmedien für eine spätere Verteilung (globale Netze, CD-ROM, interne Netzwerke ...) berücksichtigt werden. • Für die technologieunabhängige Langzeitarchivierung empfehlen sich dagegen 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 ausdehnen. Mit entsprechenden künftigen Redigitalisierungsmethoden können die Dokumente wieder in elektronische Strukturen konvertiert werden. 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. Zudem können bei geeigneter Wahl des Mediums (neue Entwicklungen verwenden 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 Bauzustand die passende Technische Dokumentation zuzuordnen und Änderungen im Rahmen des Pflegeaufwands nachzuvollziehen. Bei Fehlern in überarbeiteten Dokumenten kann auf einen früheren Zustand zurückgegriffen werden. Ältere Versionen sollten archiviert werden, damit jederzeit auf alle ausgelieferten 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 Entwicklungsarbeiten begonnen und organisiert werden, dass ausreichend freigegebene 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 –


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 publishing systems. Once specified document frameworks can thereby be filled in with contents by independently working documentation teams. For publication in various media, the appropriate processing tools are needed in addition 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-resolution 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 microscope – 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. Additionally, the data can theoretically remain preserved in reproducible state over thousands of years if the suitable medium is selected (new developments use less corrosive metal substrates). 5.5.3

Version control

To be able to explicitly identify documents in various versions, various statuses 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 accessed at any time. In particular while using content management systems, special emphasis must be laid on this requirement, since not all content management systems offer this function comprehensively. 5.5.4

Delivery

Each piece of technical documentation is a part of the product and must be delivered simultaneously with the product according to statutory regulations. All activities concerning developing, checking and finalisation of the technical documentation must therefore be begun and organised synchronously and concurrent with the development work, such that sufficient approved technical 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 definierten Zustands

Dokumentation nach Umbau und Modernisierung

Nachdokumentation im Bereich Software und Steuerung

Im Rahmen der Inbetriebnahme kann es in der Praxis zu Änderungen des Pr odukts 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 Vertrag definierten Zeitpunkt ab. Die Dokumentation nach Umbau und Modernisierung entsteht meist im Bereich 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 widerspiegeln. Nur auf diese Weise ist eine weitere sichere technische und wirtschaftliche Nutzung möglich. Nachdokumentation, die im Bereich der Entwicklung von Software und Steuerung 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, Wartung und Weiterentwicklung möglich.

6 Qualitätsmanagement

Begriffe

Wie jedes andere Produkt soll auch die Technische Dokumentation eine bestimmte Qualität aufweisen, die durch systematische Prüfung der Einhaltung von definierten Prozessabläufen erreicht wird. Zugleich ist auch die Wirksamkeit dieser Prozesse zu prüfen. Wie bei jedem anderen Produkt setzen die Qualitätsprozesse bereits in der Konzeptionsphase einer Technischen Dokumentation ein und begleiten sie bis zum Ende des Produktlebenszyklus. Über das Qualitätsmanagement werden die Verfahren zum Nachweis der gewünschten Dokumentationsqualität festgelegt. Zu den Verfahren gehören unter anderem: • Definieren der zu betrachtenden Qualitätskriterien und der zu erreichenden 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 Beseitigung der Mängel Die Qualitätssicherung sorgt im Planungs- und Erstellungsprozess einer Technischen Dokumentation für die Einhaltung der vom Qualitätsmanage-

– 46 –


Quality management Adapting of documentation

Documentation of a defined condition

In the course of commissioning, changes can be made to the product in practice. 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 status 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 and modernisation

Documentation after reconstruction and modernisation is created mostly in 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 documentation 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 of software and control system

Post-documentation that is created in the area of development of software and 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 documented, 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

Terms

Like every other product, technical documentation too must exhibit a certain quality, which is achieved by systematic checking of the com pliance with defined 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. 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 assurance ensures that the processes defined by quality management are folVDI 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 Dokumentationsschritte nach festgelegten Prüfkritierien • regelmäßige Schulung von Mitarbeitern und Einweisung neuer Mitarbeiter • Überprüfen der Dokumentation in Anwendertests und/oder durch Prüfprozesse • Auswerten von Anwenderbewertungen • Audits zur Überprüfung der Qualitätssicherungsprozesse und deren Einhaltung 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 Verfahrens- oder Arbeitsanweisung im Sinne des Qualitätsmanagements dient. Nach allgemeinem Verständnis von Qualitätsmanagement reicht eine Qualitätsprüfung am Ende des Produktionsprozesses nicht aus und entspricht auch nicht dem Stand der Technik, weil sich durch die fehlende Prozessrückkopplung zu den Dokumentationsverfahren keine dauerhafte Verbesserung erzielen 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 untergeordnet, 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, Bedienungsanleitungen 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 praktischer Anwendung von Prüfkriterien empfehlenswert. Alle Erfahrungen aus gezielter Produktbeobachtung – insbesondere auch bei Wettbewerbsprodukten – sind dabei zu berücksichtigen. Zudem sollte auch der Dokumentationsprozess selbst in regelmäßigen Abstä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 unternehmensspezifisch sind. Die nachfolgend beispielhaft aufgeführten Prüfkriterien müssen produktspezifisch und anwendungsbezogen individuell ergänzt werden. – 48 –


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 described; an editorial manual is available to this end, which serves as procedural 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, customers and service providers are subordinate to the quality management in technical documentation. The following sections refer predominantly to external technical documentation, 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 revised, a weak point analysis with evaluation of the previous experiences and customer reactions as well as on the basis of practical application of test criteria 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 c reation 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 product-specific and use-oriented.


– 49 –


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 Risikobewertung ausreichend? • Sind überflüssige Sicherheitshinweise eingebaut, die auf die definierte Qualifikation der Zielgruppe nicht abgestimmt sind? • Entspricht die innere Struktur der Sicherheitshinweise den üblichen Regeln, z.B. nach der SAFE-Methode?

Dokumentation identifizieren

• Ist eine eindeutige und unverwechselbare Bezeichnung auf der Technischen Dokumentation angebracht? • Sind die erforderlichen Kontaktinformationen des Inverkehrbringers vermerkt? • Sind Angaben über den genauen Zweck, über Autor, Erstellungs- bzw. Veröffentlichungsdatum, Version enthalten? • Sind unverwechselbare Angaben zu Gerät/Maschine (Typ, Maschinennummer, Seriennummer (je nach gesetzlichen produktbezogenen Forderungen)) enthalten?

Aktualität

• Entspricht der Stand der Technischen Dokumentation dem Stand des Produkts? • Wurde die Technische Dokumentation ganz oder in den notwendigen Teilen 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 Hamburger 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 Funktionen und Sachen mit unterschiedlichen Begriffen benannt?

Sachliche Richtigkeit

• Übereinstimmung des Geschriebenen mit der tatsächlichen Situation • Entsprechen die Visualisierungselemente dem aktuellen Stand der Maschine/dem Gerät?

Inhaltliche Vollständigkeit

• Übereinstimmung beispielsweise der Kapitel in Verzeichnis mit den tatsächlichen Kapiteln • Vorhandensein aller Visualisierungselemente, auf die im Text verwiesen wird

– 50 –



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 general 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 assessment? • 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 customary 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 requirements) 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 machine/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


– 51 –


Eindeutigkeit, Konsistenz, Widersprüche

Redundanzen

Gebrauchstauglichkeit für die Zielgruppe

Aussagefähig, verständlich, lesbar, klar strukturiert, erlernbar, umsetzbar

Wirtschaftlichkeit

– 52 –

• 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 normativen Vorgaben? • Vereinheitlichung der Begrifflichkeiten und der Namensgebung. Hierfür 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 • Vermeidung von Inhaltswiederholungen (Ausnahmen: Wortwiederholungen 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 Effizienz beim Leser und unterbricht den Lesefluss. • für die vorgegebene Zielgruppe und innerhalb eines gegebenen Benutzungskontexts ausgewogene Inhalte mit der dafür angemessenen Präzision • angepasst an das vorausgesetzt vorhandene Wissen, an die Intelligenz und den Benutzungskontext der Zielgruppe sowie angepasst an die eingeschätzten soziokulturellen und psychologischen Eigenschaften der Zielgruppe • „Zufriedenstellend“: Der Anwender verspürt die emotionale Empfindung, mit der Leistung des Produkts einverstanden zu sein und nichts auszusetzen zu haben. • Erfüllung des Wunschs, den empfundenen (oder teilweise auch tatsächlichen Mangel) durch das Befolgen der Technischen Dokumentation behoben zu haben, womit die sogenannte erlebte Nutzungsqualität der Erwartungshaltung entspricht • der Zielgruppe angemessener Wortschatz (bezüglich der Wortlänge, Bekanntheit der Worte usw.), Satzbau (Länge, Art, Aufbau) und andere Textfaktoren • Kürze, Einfachheit und Prägnanz, um richtig und schnell verständlich zu sein • aufgeteilt in Kapitel, die sich soweit möglich inhaltlich nicht überschneiden 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) • 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-Publishing)



Unambiguity, consistency, contradictions

Redundancies

Fitness for use by the target group

• 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 normative specifications? • Standardisation of concepts and appellation. Advantageous in this respect is the existence of rules that help to achieve and control this standardisation (terminology specifications). • uniformity of formulations, e.g. always “turn in the screw”, not alternately “screw in the screw” or “tighten the screw” • correctness of all links in the texts, no unresolved cross-references • 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. • contents that are composed for the specified target group and within a given context of use with the adequate amount of precision • adjusted to the knowledge that is assumed to exist, adjusted to the intelligence 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

Meaningful, comprehensible, legible, clearly structured, learnable, implementable

Economic efficiency

• vocabulary that is apt for the target group (in respect of word length, level of awareness of the words, etc.), sentence structure (length, type, structure) and other text factors • briefness, simplicity and conciseness, in order to be correctly and quickly comprehensible • divided into chapters that do not overlap in terms of content as far as possible 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) • 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)


– 53 –

Qualitätsmanagement Prüfungen am Produkt

• konform konform zu gesetzlic gesetzlichen hen Anforderu Anforderungen, ngen, produk produktabhä tabhängig ngig • kon konfor form m zu hausint hausintern ernen en Regelu Regelunge ngenn

Gesetzes- und normenkonform

6 .2

Prüfungen am Produkt

Ist die Technische Dokumentation nach einer Checkliste entsprechend den Prüfkriterien geprüft, sollten auch auc h Akzeptanzprüfungen am Produkt mit unvorbereiteten Testpersonen der vorgesehenen Zielgruppe durchgeführt werden. Gegebenenfalls sind Prüfungen des Produkts durch eine übergeordnete Prüfstelle (TÜV, (TÜV, UL, Benannte Stelle) notwendig. Hierbei wird auch die Technische 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 Antworten auf folgende Fragen: • Wie lange lange brauchen brauchen Testper Testpersonen sonen bis zur zur Inbetriebnah Inbetriebnahme me und Nutzung Nutzung des Produkts (Bedienschnelligkeit)? ( Bedienschnelligkeit)? • Welche und wie viele viele Bedienschri Bedienschritte tte werden erfolgre erfolgreich ich vollzogen vollzogen?? • Welche der verschi verschiedenen edenen Produktfu Produktfunktio nktionen nen werden im ersten ersten Anlauf genutzt? • Wie lange lange dauern die einzelnen einzelnen Schritte Schritte (Soll-Is (Soll-Ist-V t-Vergl ergleich)? eich)? • Welche Unklarheit Unklarheiten en oder Schwierigk Schwierigkeiten eiten entstehen entstehen beim beim ersten Nutzen Nutzen des Produkts? • Wie hoch hoch ist die die Zufriedenhe Zufriedenheit it des Anwender Anwenderss mit dem Produkt Produkt und und seiner Bedienung? • Wie ist ist die Einstellun Einstellungg des Anwenders Anwenders zum Produkt Produkt (technis (technische che KompleKomplexität, Bedienungsfreundlichkeit usw.) vor und nach dem Test? • Mit einstufigen V Verfahren erfahren 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 sowohl die Produktgestaltung als auch Art, Gestaltung und Inhalt de r Benutzerinformation zielgruppenkonform beeinflusst werden; sie sind deshalb gegenüber dem einstufigen Verfahren Verfahren zu bevorzugen.

Verfahren

Untersuchungsmethoden

Für Akzeptanzuntersuchungen stehen verschiedene Methoden zur Verfügung, die unterschiedlich hohen Aufwand erfordern und die an ebenso verschiedene Voraussetzungen Voraussetzungen gebunden sind. Es werden im Wesentlichen Methoden aus der Marktforschung angewendet (z.B. Lückentest, Behaltensoder 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 oder nach der Produkteinführung angewendet werden.

Untersuchungsmethoden vor der Markteinführung

Vor der Produkteinführung bieten sich z. B. an:

– 54 –

• Bef Befragung Die Befragung von Testpersonen vor oder nach einem Benutzertest unter gleichzeitiger Beobachtung ihres Verhaltens Verhaltens (siehe unten) ist in der Praxis die am weitesten verbreitete und wirksamste Methode.


Quality management Acceptance tests with the product itself

• consistent consistent with with statuto statutory ry requirement requirements, s, product-de product-depende pendent nt • con consis sisten tentt with with in-h in-hous ousee rules rules

Consistent with law and standards

6.2 6. 2

Acce Ac cep pta tan nce te test sts s wit with h the the pr prod oduc uctt its itsel elff

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

Acceptance tests

The technical documentation should communicate the appropriate knowledge effectively and surely, so that the users can convert these informations into actions directly and without any doubts. Answers to the following questions serve as criteria for this: • How long long do the test test persons persons need up to to commissionin commissioningg and use of of the product (promptness of operation)? • Which and and how many many operatin operatingg steps are are successful successfully ly performed? performed? • Which of the the various various product product functions functions are used used in the first first start-up? start-up? • How long long do the individua individuall steps last last (target-act (target-actual ual comparison comparison)? )? • Which ambigui ambiguities ties or difficul difficulties ties occur occur when the product product is used used for the first time? • How high high is the satisfa satisfaction ction of the the user with with the product product and its operati operation? on?

Process

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

Test methods

• In ca casse of multiple-step processes in parallel with the product development, 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 processes. Various methods are availabl availablee for acceptance tests, which require various degrees 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 the product introduction.

Test methods prior to market market entry

Prior to product entry, the following methods present themselves: • survey Survey of test persons before or after a user test while simultaneously observing 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 Technischen Redakteur

• Beob Beobac acht htun ungg Bei diesem Test wird das Produkt mit seiner Benutzerinformation verschiedenen 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 Produktanwendungen durch. Die Beobachtung erfolgt offen, das heißt, der Testperson ist bewusst, dass sie beobachtet wird. Das Erfüllen der Zielvorgaben, Bedienschnelligkeit, erfolgreich absolvierte Bedienschritte sowie benötigte Zeiten lassen sich auch durch Nichtfachleute zweifelsfrei und direkt auswertbar ermitteln. Die Aufzeichnung der Versuchsdaten sollte durch technische Hilfsmittel (Audio-/Videoaufzeichnung) unterstützt werden. • int intern ernee Vorp orprüf rüfung ungen en Anhand von Checklisten werden von Mitarbeitern unterschiedlichster Abteilungen (z.B. Marketing, Vertrieb, Service, Technische Redaktion) einzelne Forderungen auf ihre Erfüllung hin überprüft, um Verbesserungsoder Änderungsbedarf zu ermitteln. Die Checklisten sind nach den Prüfkriterien (siehe oben) produktspezifisch und anwendungsbezogen zu erstellen. Des Weiteren können Labortests mit Prototypen, Expertenbefragungen sowie spezielle Anwendertests durchgeführt werden. Bei Letzteren wird unterschieden zwischen • inte intern rnen en Tes Tests ts (mit Mitarbeitern des Herstellers, Händlern oder Verkaufspersonal) Verkaufspersonal) und • ex extter erne nenn Tes Tests ts (mit Mitarbeitern wichtiger Kunden oder zufällig ausgewählten Erstbenutzern 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 na ch Abschluss dieser Prüfungen und nach ihrem gezielten Auswerten durch die für Gestaltung, Vertrieb Vertrieb und Kundendienst verantwortlichen Führungskräfte erfolgen. Besonders wichtig ist der Nachweis der Erfüllung aller Sicherheitsanforderungen aus Rechtsnormen und allgemein anerkannten Regeln der Technik. Auch nach der Produkteinführung können Akzeptanzuntersuchungen, z.B. durch Expertenbefragungen, nützlich sein. Dabei werden das Wissen und die praktische Erfahrung externer Spezialisten oder Gutachter genutzt.

Untersuchungsmethoden nach Markteinführung Markteinfü hrung

Es können auch Organisationen wie die Stiftung Warentest, VerbraucherorgaVerbraucherorganisationen oder Technische Überwachungsvereine hinzugezogen werden. Empfehlenswert ist es, bei Prüfungen erfahrene Mitarbeiter des Verkaufs oder des Kundendiensts einzubeziehen, die Erkenntnisse aus der Nutzung ähnlicher Produkte einbringen können. 6.4 6. 4

Anfo An ford rder erun unge gen n an de den n Tec Techn hnis isch chen en Re Reda dakt kteu eurr

Ausbildung und Qualifikation des Erstellers von Technischer Dokumentation, des „Technischen Redakteurs“, spielen bei der Qualitätsdefinition eine wesentliche Rolle. Das Aufgabenfeld des Technischen Redakteurs ist angesichts der vielfältigen Arbeitsbereiche höchst komplex und entsprechend anspruchsvoll 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 –


Quality management Requirements that the technical writer must meet

• monitoring In this test, the product with its user information is made available to various test persons. In the monitoring phase, the test persons put the product into operation with the help of the external documentation, reproduce operating 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 recording). • internal preliminary tests Based on checklists, employees from diverse departments (e. g. marketing, distribution, service, technical editorial department) check individual requirements for their fulfilment, to determine any need for improvement or change. The checklists must be product-specific and use-oriented according 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 users of the target group). Both product design and contents of technical documentation are to be repeatedly tested with these methods for the acceptance test. The approval for production of the product and of the final contents of the technical documentation should be given only after conclusion of these tests and after their selective 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. Even after product entry in the market, acceptance tests can be useful, e. g. using surveys addressed at experts. In the process, the knowledge and the practical experience of external specialists or appraisers are used. Organisations such as Stiftung Warentest, consumer organisations or technical surveillance agencies can also be drawn upon. It is recommendable to include experienced employees from sales and customer service during tests, who can contribute their findings based on use of similar products.

Test methods after market entry

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 manufacturer 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 benö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 Systematik und Zuverlässigkeit notwendig. Ausbildungsgänge mit dem Abschluss des Technischen Redakteurs werden an vielen Hochschulen und als Weiterbildungsangebot 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 da rzustellen. 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 Ressourcenplanung 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 Bedingungen, 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. Beauftragen 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 Kommunikationsmittel zwischen Hersteller und Anwender erfüllen. Sie m uss sehr hohen Qualitätsanforderungen bezüglich Inhalt und Gestaltung gerecht werden. Das zu erreichen und zu verwirklichen ist Aufgabe des Technischen Redakteurs.

– 58 –


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 knowledge 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 reliability is required. Educational courses with leaving examination for qualification as technical writer are offered at many colleges and are also offered as further education courses at further educational institutes, by independent educational institutions and professional associations. Based on his didactic ability, the technical writer must be in a position to represent complex technical contents in an understandable, target-group oriented, clearly arranged, logical and factually correct way. He must be in a position 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 documents 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 assigning the creation of the corresponding graphics, illustrations and photos, 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 communication between manufacturer and user. It must meet very high quality requirements with respect to content and layout. It is the task of the technical writer to realise this.


– 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 Materialien, CD-ROM, Internet usw.) möglich, wobei jedoch eine einheitliche Datenbasis genutzt werden kann. Diese einheitliche Datenbasis wird medienneutral verwaltet und gespeichert. Texte, Bilder und andere grafische Elemente 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 Einspar ungen

erzielen lassen.

Dokumentation

Durchgängige, systematische Zusammenfassung und Bearbeitung von aufgezeichneten Informationen zum Aufbewahren, Klassifizieren, Wiederfinden, Nutzen und Verbreiten. [in Anlehnung an ISO 5127-1]

Externe Technische Dokumentation

Beinhaltet alle technischen Informationen über Produkte, die von einem Hersteller/Vertreiber für Vertrieb, Anwender und Verbraucher bestimmt sind, und dient der Produktnutzung durch den Anwender. Anmerkung: Die Dokumentenarten und Dokumentationsproze sse 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 Verständlichkeitsmodell

Ein bekannt gewordenes Modell über verständliche und erfolgreiche Sprache. 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 Dokumentation

Beinhaltet alle technischen Informationen über ein Produkt, die im Unternehmen 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

– 60 –

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öglichen. 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: “aftersales 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 individual 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 information for retention, classification, recovery, use and dissemination. [adapted from ISO 5127-1]

External technical documentation

Technical manufacturer/distributor information about products that are meant 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 respective 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 comprehensibility

Model of comprehensible and successful language in technical documentation, which prioritises the following comprehension criteria: simplicity, structuring and order, briefness and conciseness as well as the additional stimulation. 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 se ntences. For this, the types of sentences are ma rked 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 institutional in nature.

Internal technical documentation

Technical information about products that remain in the company, for instance, 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 documentation 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 favourable flow of reading experience.


– 61 –


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 Menschen verbessern.

Persona-Methode

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

Pflichtenheft

Dokument, das in konkreterer Form beschreibt, auf welche Weise die produkt- 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 Verantwortlichkeiten, Prozesse und erforderlichen Mittel für die Qualitätspolitik eines 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), Geldmittel, Personen und (Arbeits-)Zeit, die notwendig sind, um den Vorgang der Erstellung 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 Risiken, ihrer Eintrittswahrscheinlichkeit und möglichen Folgen. Die so bewerteten Risiken werden dann mit vorher definierten Risikokriterien abgeglichen.

SGML

SGML (Standard Generalized Markup Language, generalisierte Standardauszeichnungssprache); Metasprache zur einheitlichen Definition unterschiedlicher 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 Weiterentwicklung 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 Dokuments durch Elemente definiert bzw. strukturiert. Diese Elemente werden jeweils durch einen „Tag“ („Etikett“, „Markierung“) dargestellt. Tags sind Kürzel, die in spitzen Klammern eingeschlossen sind, und dienen dazu, Textelemente ausz uzeichnen. SGML bietet ideale Voraussetzungen für die Erstellung von Dokumenten auf Grundlage einer Datenbasis.

– 62 –



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 complex contexts can be improved for people with the help of modularity.

Persona method

Established procedure for realising →target group analysis

Performance specifications

Document that describes in concrete terms as the way in which the productand documentation-specific requirements of the →tender specifications shall be recorded in writing as binding. According to DIN 69905, these are “realisation specifications developed by the contractor based on the implementation 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, rationalising 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 possible consequences. The risks thus evaluated are then reconciled with previously defined risk criteria.

SGML

SGML (standard generalised markup language); metalanguage for standardised 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 brackets, and serve to mark up text elements. SGML offers ideal prerequisites for the creation of documents on the basis of a database.


– 63 –


Single-Source Publishing

Verfahren für die Verwaltung, Lenkung, Archivierung und Bereitstellung 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 erreichen.

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, BGVA 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 Dokumentation (TD)

Sammelbegriff für alle Dokumente über technische Produkte, Prozesse und 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 geschieht in Form von →Lasten- und →Pflichtenheften, Werbeschriften, Produktbeschreibungen, Gebrauchs- und Betriebsanleitungen, Wartungshandbüchern, Teilekatalogen, Programmieranleitungen u.a.

Unternehmensprozess

Kernprozesse, Führungsprozesse und Unterstützungsprozesse eines Unternehmens. 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 Geschä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ührenden Tätigkeiten über den gesamten Produktlebenszyklus werden in einer geordneten 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 Nu t-

zer hinsichtlich ihrer Tätigkeiten und typischen Erfahrungen zu kommen.

XML

XML (Extensible Markup Language, erweiterbare Auszeichnungssprache). 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 Vorteile bietet. Anmerkung: XML-Dokumente sehen ähnlich aus wie HTML-Dokumen te: Sie enthalten in spitze

Klammern eingefasste „Tags“. Im Unterschied zu HTML ist beim XML kein einziger ElementTyp („Tag“) von der Bedeutung her von vornherein definiert. Das bedeutet, dass jeder seine eigenen 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 –



Single-source publishing

Procedure for the management, control, archiving and provision of electronically 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 formats 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 m emorising the four essential

elements of symbol, type and source of residual risk, consequences of disregard of warning, escape.

Technical documentation (TD)

Collective term for all documents about technical products, processes and 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 engineering, installation, operation, servicing, disposal. This happens in the form of →tender specifications 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 management 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 management.

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 documents (see also →target group, →target group analysis, →persona method). Note: This procedure has proved its worth in practice for the purpose of a rriving 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 orientation as a media-neutral data format offers many advantages for data maintenance 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 printouts, simplified data exchange and increased document protection. XPS is a fixed component of


– 65 –


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.

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, soziokulturelle und psychologische Eigenschaften, Sprachverständnis, Produkterfahrung, Technikverständnis.

Zielgruppe

Anmerkung: Die Zielgruppe muss in der Technischen Dokumentation genannt werden. Dies ver-

meidet Fehlanwendungen und ist z.B. seitens des Produkthaftungsgesetzes geboten.

Zielgruppenanalyse

– 66 –

Verfahren zur Ermittlung einer auf die Zielgruppe angepassten →Technischen Dokumentation. Es werden Eigenschaften und das Verhalten von Lesern der Technischen Dokumentation untersucht, um eine möglichst gute Gebrauchstauglichkeit innerhalb eines gegebenen Benutzungskontexts zu erreichen (siehe auch →Persona-Methode, →Wer-macht-was-Matrix).



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 language, 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 documentation 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 matrix).

Schrifttum / Bibliography Gesetze, Verordnungen, Verwaltungsvorschriften / Acts, ordinances, aministrative regulations

Richtlinie 98/37/EG des Europäischen Parlaments und des Rates vom 22. Juni 1998 zur Angleichung der Rechts- und Verwaltungsvorschriften der Mitgliedstaaten für Maschinen (Directive 98/37/EC of the European parliament and of the Council of 22 June 1998 on the approximation of the laws of the member states relating to machinery). Zurückgezogen / Withdrawn 200912. 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 Directive 95/16/EC (recast)) Gesetz über technische Arbeitsmittel und Verbraucherprodukte (Geräte- und Produktsicherheitsgesetz – 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 / Technical rules

ANSI Z 535.6:2011-00 Product Safety Information in Product Manuals, Instructions, and Other Collateral Materials. Washington, D.C.: ANSI BGV A 8:2002-01 BG-Vorschrift; Sicherheits- und Gesundheitsschutzkennzeichnung am Arbeitsplatz. Köln: Carl Heymanns Verlag DIN 4844-2:2010-12 (Entwurf / Draft) Grafische Symbole; Sicherheitsfarben und Sicherheitszeichen; 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; Performing 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 61310-1:2008 (Safety of machinery; Indication, marking and actuation; Part 1: Requirements for visual, acoustic and tactile signals (IEC 61310-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 61310-2:2007); Deutsche Fassung EN 61310-2:2008 (Safety of machinery; Indication, marking and actuation; Part 2: Requirements for marking (IEC 61310-2: 2007); German version EN 61310-2:2008). Berlin: Beuth Verlag


– 67 –

VDI 4500 Blatt-4 2011-12

Recommend Documents