Erstellung einer technischen Dokumentation zur BA Verwaltungslösung "BA-Manager"

Inhaltsverzeichnis

Abbildungsverzeichnis

1 Einleitung

2 Technische Dokumentationen
2.1 Was ist eine Technische Dokumentation
2.2 Dokumentationsarten
2.2.1 Produktdokumentation
2.2.2 Benutzerdokumentation
2.2.3 Entwicklungsdokumentation
2.2.4 Projektdokumentation
2.3 Zweck einer Dokumentation
2.4 Dokumentation als Marketinginstrument
2.5 Anforderungen an die Dokumentation
2.5.1 Allgemeine Anforderungen
2.5.2 Anforderungen an eine „gute Dokumentation“
2.5.2.1 Klarheit
2.5.2.2 Kürze
2.5.2.3 Klang
2.5.2.4 Schrift
2.5.2.5 Strukturierung
2.6 Normen und Richtlinien
2.6.1 Grundlagen
2.6.2 Normen für Dokumentationen
2.6.2.1 DIN EN
2.6.2.2 VDI
2.7 Notwendige Arbeitsschritte
2.7.1 Zielgruppenanalyse
2.7.2 Informationsbeschaffung
2.7.3 Medienauswahl
2.7.3.1 Gedruckte Dokumentation
2.7.3.2 Elektronische Dokumentation

3 Dokumentation des BA-Managers
3.1 Was ist der BA-Manager
3.2 Konzept de BA-Managers
3.3 Datenschutz
3.4 Dokumentationsinhalte
3.4.1 Datenmodell
3.4.2 Attributliste
3.4.3 Installationsanleitung

4 Fazit

Literaturverzeichnis

Anhangverzeichnis

Ehrenwörtliche Erklärung

Abbildungsverzeichnis

Abbildung 1 Hypertexthilfe

1 Einleitung

Die Berufsakademie Gera verwendet zur Speicherung aller betriebsrelevanten Daten eine als „BA-Manager“ bezeichnete Software. Die Basis dieses Systems wurde in Rahmen von mehreren Studienarbeiten an der Berufsakademie Glauchau entwickelt. Im Laufe der Zeit wurde die Basis weiter verbessert und um zusätzliche Komponenten ergänzt. So existieren eine Komponente zur Unterrichtsplanung und zur webgestützten Notenauskunft, die an den BA-Manager angebunden sind. Auch diese Entwicklungen waren Teil der Studienarbeiten von Studenten. Der Fokus der Arbeiten lag dabei nur auf den eigenen Entwicklungen und der BA-Manager wurde nicht als Gesamtsystem betrachtet.

Die zuletzt angefertigte Dokumentation des BA-Managers stammt von 1999. Die Änderungen, die an dem System vorgenommen wurden, sind in die Dokumentation nicht übernommen worden. Für BA-Studenten, welche die Änderungen vornehmen, ist es jedoch wichtig, dass diese über die technischen Details informiert sind. Nur so können sie das System verstehen und ihre Komponenten systemkonform integrieren. Diese Studienarbeit soll den Dokumentationsstand aktualisieren und auf die technischen Eigenheiten hinweisen.

Im ersten Teil wird der Begriff der technischen Dokumentation erläutert und die verschiedenen Arten der Dokumentation beschrieben. Im Anschluss daran wird erörtert, welchen Zweck eine Dokumentation besitzt und angemerkt, dass eine Dokumentation in einem Unternehmen auch als Marketinginstrument verwendet werden kann, um seine Produkte besser zu verkaufen. Darauf folgend werden die Anforderungen an eine Dokumentation ermittelt. Diese sind die Grundlage dafür, dass die Dokumentation von dem Leser akzeptiert und der Inhalt verstanden wird. Im Weiteren werden die relevanten Normen recherchiert. Normen sind wichtig, damit die Dokumentation rechtskonform wird, Schäden, die aufgrund falscher Bedienung entstehen vermieden werden und der Produkthersteller vor den daraus resultierenden Schadensersatzansprüchen geschützt wird. Daran anschließend werden die Arbeitsschritte erläutert, die bei der Dokumentationserstellung besonders zu beachten sind.

Nach der theoretischen Erörterung wird auf die Dokumentation des BA-Managers eingegangen. Zunächst wird erläutert worum es sich bei dem BA-Manager handelt und wie er konzeptionell aufgebaut ist. Im Weiteren kommt es zu einem Exkurs darüber, wie der Datenschutz in dem System realisiert wird. Studienrichtungsbezogene Daten sollen nur den Mitarbeitern aus der jeweiligen Studienrichtung zugänglich sein und nur die Daten angezeigt werden, welche für zur Bearbeitung der tägliche Aufgaben der Mitarbeiter benötigt werden. Daran anschließend werden die einzelnen Dokumentationsinhalte aufgegriffen und näher erläutert. Es wird beschrieben warum diese nötig sind und warum sie in der vorliegenden Form erstellt wurden.

Ein Fazit fasst noch einmal alle Punkte zusammen und rundet die Arbeit ab.

2 Technische Dokumentationen

2.1 Was ist eine Technische Dokumentation

Technische Dokumentationen sind eine Form der Kommunikation über Technik, welche den massenmedialen Bereich betrifft. Es werden zwei Bereiche unterschieden:^[1]

Zum einen in dem Bereich der Massenmedien und zwar vor allem in der Wissenschaftsberichterstattung. Diese äußert sich in Form von wissenschaftlichen Berichten über die Technik und deren Entwicklung und trägt einen wesentlichen Anteil zur Akzeptanz der Technik in der Bevölkerung bei.

Zum andern als Kommunikationsform im Bereich der Technik, die mit Hilfe von technischen Dokumentationen erfolgt. In diesem Fall stellt die Dokumentation einen Sammelbegriff für Unterlagen zu technischen Geräten dar.

„Die Technische Dokumentation muss in übersichtlicher und logischer Form sachlich richtig alle Informationen bereitstellen, die zweckentsprechend von ihr erwartet werden, z.B. für […] Montage, Betrieb und Instandhaltung.“^[2] Um diese Anforderungen zu erfüllen kann die Dokumentation aus mehreren einzelnen Dokumenten bestehen. Diese können in Form von Handbüchern, Betriebsanleitungen, Gebrauchsanleitungen, Produktbeschreibungen, Wartungshandbüchern, technischen Tabellen, usw. erstellt werden. Die Auswahl der Dokumente und deren Aufbau wird durch die Zielgruppe vorgegeben, für welche die Dokumentation erstellt wird.

Die Ersteller solcher Dokumentationen werden als technische Redakteure bezeichnet. Dieser zweite Bereich soll hier in dieser Studienarbeit behandelt werden.

2.2 Dokumentationsarten

Dokumentationen werden für verschiedene Phasen des Produktlebenszyklus erstellt und erfüllen jeweils einen anderen Zweck. Davon und von der jeweiligen Zielgruppe hängt ab, welche Dokumentationsart verwendet wird. Folgende vier Arten lassen sich unterscheiden.

- Produktdokumentation
- Projektdokumentation
- Benutzerdokumentation

2.2.1 Produktdokumentation

Die Produktdokumentation ist eine Beschreibung der Systemeigenschaften eines Produktes, die Informationen zum Aufbau und zur Implementierung des Gerätes enthält.

Der Umfang der Dokumentation hängt von der Komplexität des Produktes und vom Einsatzzweck ab. Der Zweck kann zum einen darin bestehen als werbewirksame Beschreibung des Produktes an Kunden oder Händler verteilt zu werden. In diesem Falle werden die Funktionen und Vorteile des Produktes hervorgehoben und relativ oberflächlich beschrieben. Zum andern kann die Produktdokumentation als umfangreiche und detaillierte Beschreibung des gesamten Systems auftreten, um Fachpersonal einen detaillierten Einblick in die technischen Eigenschaften des Produktes zu ermöglichen. In diesem Fall kann die Produktdokumentation auch als Systemdokumentation bezeichnet werden.

Die Systemdokumentation muss unterschiedliche Anforderungen erfüllen. Sie sollte ausreichend abstrakt sein, um Teammitgliedern schnell und effizient einen Überblick über das System und dessen Architektur zu bieten. Jedoch muss sie auch die Bestandteile des Produktes ausreichend detailliert beschreiben. Die Beschreibung eines Softwaresystems beispielsweise müsste sowohl das Zusammenwirken der Klassen untereinander beschreiben, um einen Blick über das gesamt System zu erhalten, als auch die einzelnen Klassen, um deren Funktion zu vermitteln.

Die Beschreibung des Aufbaus sowie der Implementierung des Softwaresystems erfüllen unterschiedliche Aufgaben. Eine dieser Aufgaben ist die Bildung einer Grundlage für die Kommunikation zwischen den Projektbeteiligten. Ferner soll die Systemdokumentation die Einarbeitung in das Softwaresystem vereinfachen und dessen Weiterentwicklung und Wartung unterstützen. Auch die Systemanalytiker und die Tester benutzen sie als Grundlage ihrer Tätigkeiten.

2.2.2 Benutzerdokumentation

Die Benutzerdokumentation soll dem Anwender den Umgang mit dem Produkt ermöglichen. Der Begriff des „Benutzers“ ist in diesem Fall sehr weit gefasst. Er umfasst alle Personen, die nach der Fertigstellung des Produktes mit ihm in Berührung kommen. Dies sind sowohl die normalen Endnutzer als auch Fachpersonal wie Installateure, Wartungstechniker, Administratoren, usw. Entsprechend der Benutzergruppe muss die Dokumentation inhaltlich gestaltet werden. Um die unterschiedlichen Erwartungen der jeweiligen Zielgruppe erfüllen zu können, kann es auch nötig sein mehrere Benutzerdokumentationen zu erstellen. Dies soll jedoch unter dem Punkt Zielgruppenanalyse weiter ausgeführt werde. Mögliche Dokumente einer Benutzerdokumentation sind:

- Einführungshandbuch
- Betriebsanleitung
- Bedienungsanleitung
- Gebrauchsanleitung
- Übungshandbuch (Tutorial)
- Kurzreferenz
- Liste mit häufig gestellten Fragen (FAQ)

Die Benutzerdokumentation dient der Unterstützung der Benutzer. Sie gibt Hinweise zur Handhabung, eine Beschreibung der Funktionen und die zu ihrer Ausführung notwendigen Aktionen. Um den Benutzern den Umgang mit dem Gerät zu ermöglichen, sollten folgende Fragen beantwortet werden:

- „Was ist mit dem Programm möglich?“
- „Wie muss ich dabei vorgehen?“
- „Was passiert dabei?“

Bei der Beantwortung dieser Fragen muss Schritt für Schritt vorgegangen werden und großer Wert auf die Verständlichkeit gelegt werden. Im besonderen Maße gilt dies für die Zielgruppe der Endbenutzer, da bei diesen die Vorkenntnisse und das Verständnisvermögen am aller wenigsten eingeschätzt werden können.

Die Notwendigkeit für eine Dokumentation ergibt sich daraus, dass die Produkte meist zu komplex sind, als dass sie sich von jedem Anwender intuitiv bedienen lassen. Ein weiterer Grund für eine Benutzerdokumentation ergibt sich aus der Verantwortlichkeit, die der Hersteller für seine Produkte übernimmt. Durch falsche Bedienung des Produktes können je nach Produktart materielle oder sogar menschliche Schäden entstehen. Die Benutzerdokumentation hat die Aufgabe auf solches Fehlverhalten hinzuweisen und befreit somit den Hersteller von seiner Verantwortlichkeit für Schäden, die aus diesem Fehlverhalten resultieren. Es ist jedoch zu beachten, dass dies nicht für Schäden durch Fehler am Produkt selbst gilt.

2.2.3 Entwicklungsdokumentation

Das Wissen darüber wie ein Produkt hergestellt wird macht seinen größten Wert aus. Eine Entwicklungsdokumentation soll dieses Wissen festhalten, um die Schritte reproduzierbar zu machen. Außerdem ist sie ein wichtiges Werkzeug für die Produktentwicklung.^[3]

Während eines Entwicklungsprojektes müssen die Beteiligten über den Stand des Projektes informiert sein und auf die Ergebnisse der anderen Entwickler Zugriff haben. So lässt sich zum einen die Arbeitsteilung koordinieren. Zum andern ist dieses Wissen notwendig, um die eigenen Entwicklungen systemkonform und integrierbar zu machen. Nur wenn alle Entwicklungsteile nach den gleichen Anforderungen erstellt wurden lassen sie sich in das Gesamtsystem mit einfügen. In einem Softwareprojekt beispielsweise müsste ein Programmierer über Informationen der Schnittstellenspezifikationen verfügen, um die Übergabe der Variablen zu ermöglichen. Weiterhin müssten die Arbeitsweise und Funktionalität der Softwaremodule dokumentiert werden. Die Funktionalität wird beschrieben, um Doppelprogrammierungen zu vermeiden und so „das Rad nicht immer wieder neu zu erfinden“. Die Arbeitsweise soll späteren Programmierern die Anpassung an geänderte Anforderungen ermöglichen.

Besonders im Softwarebereich ist eine sorgfältige Dokumentation notwendig, denn schließlich wird hier das Produkt versionsweise geliefert und bestehender Programmcode immer wieder neu verwendet.

2.2.4 Projektdokumentation

Die Projektdokumentation zählt nicht direkt zu dem Bereich der technischen Dokumentationen, da sie nicht das technische Gerät beschreiben sondern lediglich den Verlauf des Projektes. Da sie jedoch den technischen Dokumentationen sehr ähnlich ist und an sie die gleichen Anforderungen gestellt werden, soll sie hier zur Vollständigkeit mit aufgeführt werden.

Projektdokumentationen sollen die einzelnen Phasen des Projektes dokumentieren, um den Projekterfolg sichtbar zu machen und um auf die erreichten Ergebnisse zurückgreifen zu können. Außerdem sollen Fehler und Misserfolge aufgezeigt werden, um diese in späteren Projekten zu vermeiden und einen effizienteren Arbeitsablauf zu ermöglichen.

Ihre Aufgabe ist die Gestaltung, Kennzeichnung und Archivierung aller angefallenen Dokumente und die Eingliederung in ein bestimmtes Ordnungssystem. Dies können Listen, Pläne, Berichte, Vorschriften, Spezifikationen und vieles mehr sein.^[4] Die Dokumentation kann sowohl statisch als auch dynamisch erfolgen.

An einer statischen Dokumentation, die auch als Abwicklungsdokumentation bezeichnet wird, wird nach Fertigstellung des Projektes keine Änderung mehr vorgenommen. Sie dokumentiert den Verlauf des Projektes um dem Auftraggeber Einblick in das Projektgeschehen zu ermöglichen und um Vergleiche zu früheren bzw. späteren Projekten zu ermöglichen.

Die dynamische Projektdokumentation wird nach Fertigstellung des Projektes weiter verändert, um das Wissen über ein sich weiter entwickelndes System auf dem aktuellen Stand zu halten. Die Dokumente werden zum Betrieb des Systems und als Wissensbasis für die Entwickler benötigt.

2.3 Zweck einer Dokumentation

Der Zweck einer Dokumentation hängt davon ab, für welche Zielgruppe sie bestimmt ist und in welchem Bereich sie eingesetzt wird. Wird ein fertiges Produkt dokumentiert, so müsste beispielsweise für den Vertrieb dokumentiert werden, welchen Leistungsumfang das Produkt besitzt. Der Endbenutzer möchte dagegen erfahren, wie er das Gerät bedienen muss, um sich die Leistungen zugänglich zu machen. Handelt es sich um eine betriebsinterne Dokumentation so werden dagegen ganz andere Eigenschaften verlangt. Diese Aspekte sollen jedoch später unter dem Punkt Zielgruppenanalyse weiter ausgeführt werden.

Die Norm DIN EN 61082 definiert den Zweck einer Dokumentation wie folgt:

„Der Zweck der Dokumentation ist die Informationsbereitstellung in möglichst einfacher Form. Die technische Dokumentation ist für Erstellung, Inbetriebnahme, Betrieb, Instandhaltung und Verschrottung einer Anlage oder eines Systems wichtig.“^[5]

Die Dokumentation soll also Informationen für jede Phase des Produktlebenszyklus bereitstellen. Diesen Phasen lassen sich auch die bereits erläuterten Dokumentationsarten zuordnen.

Allgemein lässt sich sagen, dass eine technische Dokumentation Informationen über ein technisches Gerät zu dessen Beschreibung sammeln soll. Folgende drei Hauptaufgaben werden von ihr erfüllt:^[6]

Wissenssicherung

Das Wissen (Know How) über ein System macht einen beträchtlichen Teil seines Wertes aus. Dazu muss das Wissen über das Gerät aus den Köpfen der Entwickler geholt werden. Somit wird zum einen die Erfahrung, die aus dem Projektverlauf gezogen werden kann, gesichert. Zum anderen wird die Grundlage für die Produkt- und Entwicklungsdokumentation geschaffen. Kommunikation

Eine geordnete Systementwicklung und Pflege ist nur aufgrund einer ausgereiften Kommunikation zwischen den Entwicklern möglich. Die Dokumentation dient dazu den Informationsaustausch und somit die Aufgabenteilung der einzelnen Entwickler zu realisieren. Zwischen der Informationserzeugung und der Informationsnutzung können unter Umständen Jahre vergehen. Um die Informationen dauerhaft zu erhalten, muss die Kommunikation in den wesentlichen Teilen schriftlich erfolgen. Dadurch wird die Arbeit an dem Projekt weniger personengebunden, so dass der Ausfall Einzelner nicht den Gesamterfolg gefährdet.

Sichtbarmachen des Projektfortschritts

Mit der Dokumentation des Projektes wird der Abschluss der Phasen nachprüfbar. Erst wenn die dazugehörigen Dokumente freigegeben wurden, kann die Phase als beendet angesehen werden. Später kann auf die Resultate, welche daraus gezogen wurden, einfach und schnell zurückgegriffen werden. Der Projektfortschritt wird somit besser quantifizierbar und der Ablauf des Projektes nachvollziehbar.

2.4 Dokumentation als Marketinginstrument

Lange Zeit wurden Gebrauchsanleitungen und damit Dokumentationen in den Unternehmen eher als zweitrangig betrachtet. Heute besitzt die Dokumentation in einem modernen Unternehmen jedoch einen nicht zu unterschätzenden Stellenwert. Als wesentlicher Bestandteil der Unternehmenskommunikation ist sie Ausdruck der Verbundenheit mit den Kunden geworden und ist ein wichtiges Marketinginstrument.

[...]

^[1] Vgl. [HJF96], S. 7

^[2] Vgl. VDI 4500, S. 29

^[3] Vgl. [BJ95], S. 153

^[4] Vgl. [BJ95], S. 153

^[5] Vgl. [DIN 61082], S. 33

^[6] Vgl. [MG99], S. 135