1. Software-Dokumentation tut not: Ein Lehrbeispiel

In den späten 60er Jahren als Hardware noch enorm teuer war, und die Hardware-Hersteller Software als Verkaufsargument dazugaben, arbeitete die Autorin bei der Firma Siemens in einem Team von 4 Programmierern, das für einen Kunden mehrere Programme zu schreiben hatte. Wie üblich herrschte wieder einmal Zeitdruck, und so wurden die Programme zwar termingerecht fertig und hatten auch die erforderlichen Testläufe absolviert, aber mit der Dokumentation wollte man sich Zeit nehmen bis alle Hektik vorüber sei. Das klappte auch ganz ordentlich - wie sie meinten - bei dreien von ihnen. Der vierte kündigte und versprach in recht überzeugender Weise, in naher Zukunft seine Dokumentation nachzuliefern. Er war weder mit guten Worten noch mit Repressalien dazu zu bewegen, seine Dokumentation gleich fertig zu machen; und so blieben seine Programme undokumentiert.

Siemens hatte ein neues Betriebssystem herausgebracht, und der Teufel, der ja bekanntlich im Detail sitzt, wollte es, daß just eines seiner Programme als erstes geändert werden mußte. Es existierte ein Sourcecode-Listing, das Sourcecode-Kartendeck und das Objektcode-Kartendeck. Das absolute Chaos begann: Das Programm war in Assembler geschrieben, und da der Programmierer ein sehr trickreicher war, hatte er die letzten Programmfehler durch Anfügen sogenannter REP-Karten (Replacement-Karten) an das Objektdeck beseitigt. Das sparte damals mächtig Kompilierzeit (etwa 30 min, aber nur 3-4 mal am Tag) und Lochkarten für ein neues Objektdeck. Somit war also auch das Listing veraltet. Trotzdem versuchten wir, uns mit seiner Hilfe in die Programmlogik einzuarbeiten. Nach 3 oder 4 Tagen gaben wir auf, zumal zu dieser Zeit noch die Programmierung mit "goto" total in war, was nicht gerade die Lesbarkeit eines Programms unterstützt. Es endete damit, daß einer von uns das Programm neu schreiben mußte. Das wiederum bedeutete für den Kunden eine Verzögerung um etwa einen Monat. Für uns bedeutete es nicht nur, daß einer in unserem aktuellen Projekt fehlte sondern auch, daß wir uns den Unmutsäußerungen des Kunden ob unserer mangelnden Professionalität ausgesetzt sahen.

Dieses Programm wurde dann besonders sorgfältig dokumentiert nach den Regeln, die damals galten. Was alles dazu gehörte, wird im Punkt 2.1 zu lesen sein. Als wir dann aber bei dieser Gelegenheit unsere anderen früheren Prorammdokumentationen auf das durchsahen, was man heute mit "Corporate Identity" bezeichnen würde, waren wir so richtig froh, daß diese Programme bislang noch ohne Änderungen ausgekommen waren! In jeder Dokumentation fehlte irgendein wesentlicher Teil. Herausgefunden haben wir es dadurch, daß wir die bei Siemens sonst nur beim Programmtest übliche Methode angewandt hatten: Teste nie Dein eigenes Programm sondern das eines anderen!

Am Ende gingen wir in unser Lieblingspub und beschlossen, bei allen folgenden Projekten projektbegleitend und so umfassend wie möglich zu dokumentieren, damit jeder andere Programmänderungen vornehmen könne und es uns nicht gehe wie manchen Kollegen, die noch Jahre nach Fertigstellung ihrer Programme immer wieder angerufen wurden, ob sie nicht eben mal schnell eine kleine Änderung vornehmen könnten.

 

2. Software-Dokumentation in den Jahren 1960 - 1990

Auch wenn der Titel es einem suggeriert: Es gab fast keine Gemeinsamkeiten in der Art und Weise der Dokumentation in dieser Zeit. Die Software-Dokumentation war abhängig von der Hardware, von der Firma, vom Ausbildungsstand der Programmierer - ein regelrechtes Informatikstudium gab es in Deutschland erst ab Anfang der 70er Jahre - und von allen möglichen anderen Faktoren.

 

2.1 Die wilden 60er Jahre und die Lochkarten

Die Hardware der 60er Jahre sah eine Programmeingabe in den allermeisten Fällen über Lochkarten oder Lochstreifen vor, die mit dem Teletype erstellt worden waren. Daher sah eine typische Mainframe-Konfiguration folgendermaßen aus: CPU, Teletypekonsole zur Kommunikation mit der CPU, Lochkartenleser, Lochstreifenleser, Lochkartenstanzer, 1-2 Magnetbandstationen, Kettendrucker. Programme bestanden zu allermeist aus 1000 - 2000 Karten (= Lines of Code). Programmierer konnte jeder werden, der einen Lehrgang bei einem der bekannten Computerhersteller absolviert hatte. So pflegte jeder seinen eigenen Programmierstil und dokumentierte wie er wollte. Allein bei den großen Firmen herrschte ein gewisses Maß an Ordnung und ein Reglement, an das man sich zu halten hatte. Das galt insbesondere für Firmen wie Siemens oder IBM, die ihre Hardware mit der brauchbarenSoftware als Dreingabe verkaufen wollten.

Daher gehörte dort zu einer vollständigen Programmdokumentation:

verbale Programmanforderungen bzw. Programmauftrag

Die folgenden Teile waren nur notwendig, wenn sie in dem Programm auch angesprochen wurden:

Um ein lückenlos fortlaufend numeriertes Sourcecode-Kartendeck zu bekommen, mußte man meist das letzte Deck duplizieren und mit neuer Numerierung versehen. Bei der ersten Erstellung der Programmkarten wurde stets eine 8-stellige Numerierung in den Spalten 73-80 in hunderter Schritten vorgenommen, damit man Lücken hat, um Änderungskarten während des Testens leicht einfügen zu können. Der Alptraum jedes Programmierers war nämlich, daß die Programmkarten herunterfallen und man sie manuell nach dem letzten Listing wieder sortieren muß. Bei einer lückenlos fortlaufenden Numerierung konnte man das Deck in einer Sortiermaschine sortieren lassen. Nun wurde aber in der heißen Phase des Testens häufig das Gesetz der Weiternumerierung mißachtet. Für die Dokumentation aber, die ja von ihrer Philosophie her für andere als einen selbst bestimmt war, mußte man "heile Welt" zeigen.

Das best gehaßte Stück Programmdokumentation war der Programmablaufplan, der sogenannte "Wandteppich". Vor Beginn der Programmierung hatte man einen erstellt, weil er Gegenstand von Vorbesprechungen in der Analysephase war. Er wurde dann als Arbeitsgrundlage an der Wand aufgehängt, was sehr eindrucksvoll wirkte. Während der Testphase hingegen wurde er - wenn überhaupt - nur unzureichend und lieblos aktualisiert. So mußte man sich nach Beendigung des Programms hinsetzen und in mühsamer Kleinarbeit einen Programmablaufplan zeichnen. Nachdem er schön gefaltet im Ordner eingeheftet worden war, hat ihn niemand - dessen bin ich mir fast sicher - jemals wieder angeschaut!

 

2.2 Die Magnetbänder der 70er Jahre

In den 70er Jahren ging die Entwicklung hin zu größeren Mainframe-Anlagen. Die Primäreingabe der Sourcecodes wurde zum größten Teil immer noch über Lochkarten vorgenommen, aber die Objektcodes wurden auf Magnetbändern oder Platten ausgegeben, was die Kompilierungszeiten von etwa 20 - 30 min auf ungefähr die Hälfte herabsetzte. Diese immer noch langsame Zeit war dabei durch den Kartenleser zu erklären.

Die Hardwareveränderung hatte aber auch Auswirkungen auf die Art der Programme. Eine Programm- und Aufgabenintegration fand statt. Was zuvor mehrere kleine Programme mit zwischengeschalteten Sortier- oder Mischläufen waren, wurde nun zu umfangreicheren und komplexeren Programmen zusammengefaßt. Das hatte natürlich auch Auswirkungen auf die Art der Programmdokumentation: Die Datenflußdiagramme wurden einfacher, aber die "Wandteppiche" wurden immer größer und beeindruckender aber immer unübersichtlicher. Die Kartons mit mit Objektcodes wichen einem Formular, auf dem die Nummer des Magnetbandes oder die Adresse der Platte vermerkt war, worauf die Objektcodes gespeichert waren.

Bei Siemens und anderen Herstellern gab es die ersten Ansätze einer Art Dokumentationsautomatisierung. Es existierte ein Programm, das aus dem eingegebenen Sourcecode einen Programmablaufplan generierte. Der wurde dann noch umfangreicher als der handgezeichnete und sah meist noch etwas unübersichtlicher aus, aber er hatte den unschätzbaren Vorteil schnell und ohne eigene Handarbeit fertig zu sein - natürlich auch erst nach Abschluß der Programmierarbeiten.

Hatte die Autorin noch 1971 in einer Versicherungsgesellschaft 6 Millionen Lochkarten in Räumen voller Regale gesehen, die täglich unter Einsatz des Computers bewegt wurden, so war der Vormarsch der Magnetbänder nicht mehr aufzuhalten. In den folgenden Jahren wurden nicht nur die Objektcodes, d.h. die ablauffähigen Programme auf Magnetbändern gespeichert sondern allmählich auch alle Daten. Obwohl ein Magnetband mit seinen 10 Zoll Durchmesser immer noch etwa so groß war wie eine Filmrolle und in speziellen feuerfesten Metallschränken aufbewahrt werden mußte, ließ sich allein die Platzersparnis bei der Datenspeicherung in "Anzahl von Räumen" ausdrücken.

Für die Programm-Dokumentation bedeutete dies und der Trend zur Zusammenfassung kleiner Programme zu einem größeren, daß sich auch hier Einsparungen bemerkbar machten.

 

vorher

nachher

Anzahl Programme

30

10

Anzahl Kästen mit Lochkarten (Sourcecode)

30

10

Anzahl Kästen mit Lochkarten (Objektcode)

30

----

Anzahl Aktenordner für Papierdokumentation

30

10

Anzahl Magnetbänder

----

2

 

2.3 Der Umbruch in den 80er Jahren

Eine wirkliche Wende sowohl in der Programmierung als auch in der dazugehörigen Dokumentation brachten die 80er Jahre mit den Terminals als neuen Peripheriegeräten. Sie waren im Vergleich zu der restlichen Hardware billig und benötigten keine klimatisierten Räume. Damit verschwanden zunächst einmal die letzten schwerfälligen Lochkarten, da ja nun die Programmierer über die Terminals ihre Programme direkt eingeben konnten. Gleichzeitig begann eine weitere Miniaturisierung der Datenträger. Die gegenüber den Magnetbändern erheblich billigeren Disketten eroberten den Markt.

Für die Software-Dokumentation bedeutete dies, daß man leicht ein Programm, eine kurze zugehörige Programmbeschreibung und ein Testbeispiel zusammen auf einer Diskette speihern konnte.

Doch eine noch viel entscheidendere Bedeutung für die gesamte Philosophie der Datenverarbeitung zeichnete sich ab: War bis dahin die Benutzung eines Programms fast ausschließlich Sache der Arbeitsvorbereiter, Operator und Programmierer im gegenüber den Fachabteilungen hermetisch abgeschlossenen und klimatisierten Rechenzentrum, so war es nun möglich, Terminals mit Eingabetastatur in den Arbeitsräumen von Fachabteilungen zu installieren.

Für die Programmierung bedeutete dies eine entscheidende Änderung der Zielgruppe, für die sie programmierten. Der Dialog mit dem Programmbenutzer mußte vorgesehen werden, und die Dokumentation der Programme mußte zwei verschiedene Gruppen ansprechen: nach wie vor die EDV-Abteilung und neuerdings die Fachabteilung.

Die EDV-Abteilung benötgte nun:

und falls sie im Programm angesprochen wurden:

Die Fachabteilung benötigte:

Eine weitere epochemachende Hardware-Neuerung trat auf den Plan: die PC’s. Sie waren um Größenordnungen billiger als die traditionellen Mainframe-Anlagen und benötigten ebenfalls keine klimatisierten Räume mehr. Das bedeutete für die Firmen, daß immer mehr Fachabteilungen mit eigenen, vom Rechenzentrum unabhängigen Rechnern ausgestattet wurden. Damit ging die Verantwortung für den Betrieb des jeweiligen PC’s an "EDV-Laien" über. Mit der billiger werdenden Hardware entschlossen sich die Hersteller zum Verkauf ihrer Software, und gleichzeitig drängten neue Software-Anbieter auf den Markt.

Das wiederum bedeutete, daß auch ganz neue Ansprüche an eine Software-Dokumentation gestellt werden mußten. Man brauchte:

Da ja die Software verkauft wurde, blieben natürlich alle Unterlagen, die den Sourcecode betrafen, beim Software-Hersteller. Das hatte dann zur Folge, daß eine strikte Zweiteilung von Software-Dokumentation vorgenommen werden mußte nach der Frage: Für wen ist die Dokumentation bestimmt? Das führte zu einer Dokumentation für Kunden nach außen und einer für firmeninterne Zwecke nach innen. Danach erst konnte eine Unterteilung nach Benutzern in Fachabteilungen (Laien) und Administratoren in EDV-Abteilungen (Experten) erfolgen.

 

3. Software-Dokumentation in den 90er Jahren

Mit dem Vormarsch der PC’s nahm die Menge der EDV-Laien als Software-Benutzer sprunghaft zu. Viele konkurrierende Software-Produkte drängten auf den Markt, und der Ruf nach Standardisierung wurde unüberhörbar. Diesen Ruf vernahm man auch in Berlin im Deutschen Institut für Normung. Die Software mußte vermarktet werden und sich weiterentwickeln, um konkurrenzfähig zu bleiben. Damit kamen auf die Dokumentation neue Anwendungsgebiete zu, nämlich die Marketing-Dokumentation und die Entwicklungs-Dokumentation.

 

3.1 Normen

Herrschte vor 1980 teilweise Unsicherheit über das "wie" und "was" der Software-Dokumentation, so konnte man sich als Programmierer nun an die DIN-Vorschriften halten. Die nachfolgende Übersichtstabelle enthält die wesentlichen Normvorschriften für Software-Dokumentation:

DIN Nr.

Bedeutung

66001

Symbole für Datenflußpläne

66001 Beiblatt 1

Zeichenschablone Symbolen für Datenflußpläne

66002

handschriftliche Darstellung von "O" und null

66230

Inhaltsverzeichnis von Programmdokumentation

66230 Beiblatt 1

festes Inhaltsverzeichnis von Programmdokumentation

66231

Programmentwicklungs-Dokumentation

66232

Datendokumentation

66241

Entscheidungstabellen, Beschreibungsmittel

66261

Struktogramme nach Nassi-Shneiderman

69900-1

Netzplantechnik: Begriffe

69900-2

Netzplantechnik: Darstellungstechnik

Ab den 80er Jahren unterlagen Programmablaufpläne und Datenflußpläne - was die benutzte Symbolik anbetraf - Normen. Diese wurden in der Norm DIN 66001 festgelegt. DIN 66001 Beiblatt 1 standardisiert eine Zeichenschablone zur Erstellung vorgenannter Flußpläne. Zur Erläuterung werden hier einige Beispiele gezeigt:

Symbol

Bedeutung

Kreis

Verbindungsstelle

Rechteck

Verarbeitung

Raute

Verzweigung

Die Norm DIN 66002 regelt die handschriftliche Darstellung der Zahl Null und des Großbuchstabens "O", um Verwechslungen auszuschließen.

DIN 66230 regelt auf 19 Seiten alles, was zu einer vollständigen Programmdokumentation gehört, nämlich Dinge wie

DIN 66230 Beiblatt 1 bietet sogar einen Formularvordruck dafür an. Das hat den ungemeinen Vorteil, daß man bei der Dokumentation nichts vergißt. Er besteht unter anderem aus folgenden Punkten:

DIN 66231 stellt Normen für die Programmentwicklungs-Dokumentation zur Verfügung. Darin wird aufgeführt, welche Programmentwicklungsdokumente erforderlich sind. Das sind z. B.:

DIN 66232 gibt Normen für die Daten-Dokumentation vor. Verlangt werden hier:

Alles soll dann in entsprechenden Formularen eingetragen werden.

Auch die bei vielen Programmierern beliebten Entscheidungstabellen finden ihren Niederschlag in der Norm DIN 66241. Dort gibt es Aussagen über die Else-Regel, über Bedingungen und Aktionen, über den Identifikationsteil und schließlich über die Vollständigkeit.

Da heutzutage mit der strukturierten Programmierung die Programmablaufpläne früherer Art durch Struktogramme nach Nassi-Shneiderman abgelöst wurden, hat sich auch dieses Faktum in einer Norm ausgedrückt, in DIN 66261. Ähnlich wie in DIN 66001 werden dort die Bedeutungen der Symbole für den Programmablauf festgeschrieben.

Auch die weit verbreitete Netzplantechnik als Werkzeug des Projektmanagements findet sich in Normen festgehalten. DIN 69900-1 erklärt Begriffe wie

und viele andere mehr.

DIN 69900-2 legt ähnlich wie DIN 66001 und DIN 66261 Symbole für eine graphische Darstellung fest. Die Grundformen werden definiert und die Art der Beschriftung der Darstellungselemente.

 

3.2 Dokumentations-Standards

Um der immer komplexer gewordenen Problematik der heutigen Software Rechnung zu tragen, ist es notwendig, mit Hilfe der vorbeschriebenen Normen und Formulare alle Teilbereiche zu dokumentieren. Das sind heute

Diese Dokumentationen sind für Fachleute der Computerbranche bestimmt, und für sie ist es wichtig, sich detailliert und vollständig informieren zu können und das mitt Hilfe eindeutiger Standardsymbole.

Die Benutzer-Dokumentation muß in diesem Zusammenhang gesondert behandelt werden, da sie nicht mit Standardformularen erledigt werden kann. Ihre Qualität ist ein entscheidendes Verkaufsargument für die Software. Den zugehörigen Handbüchern muß auf den ersten Blick anzusehen sein, für wen sie geschrieben wurden. Nicht so sehr der technische Standard ist hier gefragt sondern Merkmale wie ein ansprechendes Layout, Übersichtlichkeit, eine allgemein verständliche Sprache und Hilfen, um sich schnell zurechtzufinden.

In eine Benutzer-Dokumentation gehört unter anderem:

 

3.3 Qualitätsmerkmale und Methode "PentaQuest"

"Gute technische Dokumentation vermittelt einer bestimmten Zielgruppe für bestimmte Aufgabenstellungen genau die notwendigen Informationen zielgruppenorientiert aufbereitet." So lautet die Grundthese der Methode PentaQuest des Instituts für technische Literatur in München. Dieses Zitat bringt den Anspruch guter Dokumentation auf den Punkt. Die genannte Methode leitet ihren Namen von dem griechischen Wort p e n t a = fünf und dem englischen Wort question ab und bedeutet, daß man 5 Fragen stellen und beantworten soll:

Wer?

der Software-Hersteller

Wem?

der Zielgruppe, für die dokumentiert wird

Warum oder auch Wozu?

Verwendungszweck, Nutzungskategorie

Was?

notwendige Informationen

Wie?

Dokumentation muß zielgruppengerecht sein.

Es ist wichtig, daß man eine Dokumentation sofort und auf den ersten Blick erkennt und die Herkunft zuordnen kann. Das hat etwas mit Erkennungsmustern zu tun, die man schneller aufnimmt als stets wechselnde Schriftbilder. Dazu gehört etwa ein bestimmtes Pull-down-Menu, ein Logo, ein bestimmtes Layout oder der Stil. Das macht die Corporate Identity einer Firma aus.

Über die Zielgruppe wurde in Absatz 3.2 schon geschrieben, als es um Begriffe wie System- bzw. Organisationsdokumentation oder Benutzerdokumentation ging. Es ist wichtig, die Art der Dokumentation am Bedarf der Zielgruppe auszurichten. Die Benutzer sind im Normalfall keine Informatiker und möchten daher in der ihnen gewohnten Sprache informiert werden und nicht ständig über Fachausdrücke und Abkürzungen aus dem Computer-Jargon stolpern müssen.

Den Verwendungszweck darf man beim dokumentieren nicht aus den Augen verlieren. So interessiert sich der Benutzer in den seltensten Fällen für den logischen Programmaufbau. Für die Systemdokumentation ist dieser für die spätere Wartung der Software unabdingbar.

Enthalten Dokumentationsunterlagen weniger als die notwendigen Informationen, so sind sie unvollständig. Werden viel mehr als die tatsächlich notwendigen Informationen in der Dokumentation festgehalten, so können sie Verwirrung stiften.

Zielgruppengerecht ist eine gute Software-Dokumentation immer dann, wenn die Zielgruppe zuvor analysiert wurde, und sie eine entsprechend angepaßte, benutzerfreundliche Gestaltung in Bezug auf Text, Struktur und Bilder aufweist.

 

3.4 juristische Aspekte

Mit dem Kaufpreis der Software regte sich auch bei den Kunden das Bedürfnis, sich juristisch gegen Schäden absichern zu wollen, die durch mangelhaft oder uneindeutig dokumentierte Software entstanden waren. Grundlage dafür ist BGB §823 Produkthaftung. Danach wird Software-Dokumentation sogar zwingend vorgeschrieben. Software-Hersteller konnten diesem nur dadurch begegnen, daß sie auf strikte Einhaltung von Normvorschriften und allgemein anerkannten Standards bei ihrer Software-Dokumentation achteten. Ein Software-Hersteller kann auf Schadenersatz verklagt werden, wenn die Dokumentation unvollständig war und wesentliche Teile fehlten wie etwa Fehlermeldungen. So geschehen 1989 am Oberlandesgericht Hamm. Ein anderer Musterprozeß wurde 1991 am Bundesgerichtshof gegen den Hersteller der Software entschieden, weil die Betriebsanleitung nicht ausreichend darüber informierte, wie Schäden zu vermeiden seien.

Auch die EG hat sich dieses Problems angenommen und die EG-Richtlinie Maschinen 89/392/EWG herausgebracht. Sie verlangt zur CE-Zertifizierung eine definierte technische Dokumentation über sicherheitsrelevante Sachverhalte, wozu für Software die entsprechende Dokumentation gehört.

Alles, was zur Dokumentation eines Software-Produkts gehört, muß 10 Jahre lang aufbewahrt werden für den Fall einer behördlichen Nachprüfung. Bei Baustatik- oder Steuerberechnungsprogrammen erscheint dies fast selbstverständlich.

 

4 Wohin geht der Trend in der Software-Dokumentation?

Die Problematik des Dokumentierens von Software liegt in Zukunft nicht mehr so sehr bei dem einzelnen Programm des einzelnen Programmierers als vielmehr in komplexen Systemen großer (Software-)Firmen. Integrierte Software-Dokumentation ist das Zauberwort. Um ein ganzes Team von Software-Entwicklern, die parallel an einem Projekt arbeiten, während der gesamten Entwicklungszeit über alle wichtigen Änderungen auf dem laufenden zu halten, bedarf es besonderer Dokumentations-Werkzeuge. Der Anspruch an sie ist, daß die Dokumentation nicht mehr erst nach Beendigung der entsprechenden Software erstellt wird sondern von Anfang an das gesamte Projekt während aller Phasen begleitet. Ein solches Werkzeug erfüllt zugleich mehrere Zwecke:

Jeder, der selbst einmal in einem Entwicklungsteam mitgearbeitet hat, weiß wie wichtig es für denjenigen ist, der die Bildschirmmasken programmiert, rechtzeitig zu erfahren, daß die zugrundeliegende Datenbank erweitert wurde. Ohne diese Information wird fast immer "Wegwerfcode" produziert, d.h. es werden unnötig Entwicklungszeit und Produktionsmittel verschwendet, weil man Informationen zu spät bekommen hat und doppelt arbeiten muß. Im schlimmsten aller Fälle passen die zu Projektbeginn festgelegten Schnittstellen am Ende nicht zusammen. Was man sich wünscht, ist ein Werkzeug, mit dessen Hilfe man alle Anfangsbedingungen und laufenden Änderungen in geeigneter Form festhalten und bei Bedarf leicht wiederfinden kann.

 

4.1 Phasenbegleitende Werkzeuge wie "ProDok"

Phasen, die ein Softwareprodukt von Anfang bis Ende durchläuft, sind:

Ein Werkzeug, das all diese Phasen begleitet, ist zum Beispiel das Programm ProDoc der Firma Integrata. Es wurde entwickelt für komplexe Software-Systeme und arbeitet rechnergestützt mit einer Datenbank für Textdaten. Es unterstützt die Programmierung unter Windows und verwendet für seine Datenbankeinträge WinWord von Microsoft. Selbstverständlich unterstützt es auch eine Online-Hilfe-Dokumentation. In die Datenbank werden Teil-, Zwischen- oder auch Endergebnisse geschrieben. Das können sein:

Die in ProDoc abgelegten Dokumente können nach Baukastenart für verschiedene Anwendungen zusammengestellt werden. Auch ein anderer Herzenswunsch aller Software-Entwickler wird unterstützt nämlich die Möglichkeit, einmal programmierte und für gut befundene Module wiederzuverwenden. Es hilft dabei, die zu entwickelnde Software wartungsfreundlich zu gestalten und ist schließlich auch noch leicht erlernbar.

 

4.2 Arten der Software-Dokumentation

Welche Eigenschaften machen im besonderen eine gute Software-Dokumentation aus?

Verstand man in den 60er und 70er Jahren unter Software-Dokumentation im eigentlichen Sinne nur Programm-Dokumentation, so machte die Entwicklung immer komplexerer Systeme eine Unterscheidung der Software-Dokumentation nach Zielgruppen und Inhalten notwendig. Man benötigt inzwichen:

Die verschiedenen Arten der Dokumentation machen auch verschiedene Medien für die Dokumentation notwendig. Dabei werden die schriftlichen weiterhin den ersten Platz einnehmen. Daneben werden sich aber auch rein akkustische auf Kasetten oder CD-ROMs sowie visuelle in Form von Coputergraphiken und audiovisuelle wie Videos durchsetzen. Schon heute zeigt sich, daß in immer kürzerer Zeit immer mehr Informationen fließen müssen. Das gilt für Software-Dokumentation in gleicher Weise, und hören oder sehen funktioniert nun mal schneller als lesen.

 

4.3 institutionalisierte Qualitätsprüfung

Das Problem zukünftiger Software-Dokumentation liegt nicht mehr so sehr darin, überhaupt eine qualitativ gute Dokumentation zu erstellen, sondern Handbücher, Computer-Animationen und Lernvideos in großer Stückzahl zu produzieren. Jede neue Ausgabe bedeutet einen hohen Kostenfaktor. Ging bisher die Individualität der Dokumentatoren als Parameter in die Qualität der Software-Dokumentation mit ein, so darf aus Kostengründen in Zukunft nichts mehr dem Zufall überlassen werden. Heute schon richten große Firmen ein besonderes Gremium von Reviewern ein, deren Aufgabe es ist Fehler zu suchen, die Einhaltung von Normen und Standards zu überwachen, die Verständlichkeit der Texte zu überprüfen und Feldtests durchzuführen.

 

Das Reviewer-Gremium soll sich zusammensetzen aus Software-Entwicklern, späteren Benutzern, Gutachtern und einem Moderator, der als wichtigste Person die Fäden in der Hand halten und möglichst nicht aus der Riege der Entwickler kommen soll. Dabei werden Hilfsmittel wie Experteneinschätzungen, Checklisten, Audits und Walk-Throughs angewandt, um das best mögliche Ergebnis für eine gute Software-Dokumentation zu erhalten.

 

5 Quellen:

  1. DIN Deutsches Institut für Normung, 166: Software: Entwicklung, Dokumentation, Qualität 1995, 4. Auflage
  2. Hans-Peter Kränzle: Dokumentenmanagement: Technik und Konzepte, HDM Zeitschrift für Wirtschaftsinformatik Nr. 181/1995,26-43
  3. Peter Eiblmayr: Normen in der technischen Dokumentation, HDM Zeitschrift für Wirtschaftsinformatik Nr. 181/1995, 44-53
  4. Marianne Leschik: Standards für die Software-Dokumentation - Wie dokumentiere ich richtig?, 54-65
  5. Joachim Regenbogen, Bernhard Steenmann: Integrierte Software-Dokumentation, 66-71
  6. Franz Lehner: Software-Dokumentation und Messung der Dokumentationsqualität, Carl Hanser Verlag München, 1994
  7. Anneliese Ludwig-Rinn: Erfahrungen als Programmiererin bei einem Computer-Hersteller und als Leiterin der Programmierung bei einer großen Versicherungsgesellschaft