Software-Dokumentation automatisieren

Der Abschnitt beginnt mit der Feststellung, dass die Softwareentwicklung aufgrund des rasanten technischen Fortschritts und des verschärften Wettbewerbs immer komplexer geworden ist. Dies führt zu einer steigenden Notwendigkeit für eine umfassende Dokumentation des Softwareentwicklungsprozesses und der einzelnen Arbeitsschritte. Die Dokumentation wurde in der Vergangenheit jedoch oft vernachlässigt, da ein direkter, unmittelbar sichtbarer Nutzen fehlte. Die Erfassung und Aufbereitung der während der Entwicklung anfallenden Dokumente rückten in den Hintergrund. Dies hat zur Folge, dass Fehler aufgrund mangelnder Dokumentation nicht sofort oder gar nicht nachvollzogen werden können. Die wachsende Bedeutung der Dokumentation wird letztendlich auch durch die Notwendigkeit begründet, dem Softwareprodukt durch hochwertige Benutzerdokumentation einen qualitativen Mehrwert zu verleihen. Zusammenfassend lässt sich sagen, dass die zunehmende Komplexität der Softwareentwicklung und die damit verbundenen Herausforderungen die Notwendigkeit einer umfassenden und gut strukturierten Dokumentation unterstreichen, um Fehler zu vermeiden und die Qualität des Produkts zu steigern.

Ein zentrales Thema ist die negative Auswirkung unzureichender Softwareentwicklungsdokumentation. Der Text betont, dass der fehlende direkt ableitbare Nutzen zu einer Vernachlässigung der Dokumentation führt. Konkret werden die Schwierigkeiten beim Auffinden und Beheben von Fehlern aufgrund mangelhafter Dokumentation hervorgehoben. Es wird deutlich, dass Fehler in manchen Fällen überhaupt nicht mehr nachvollzogen werden können, was zu erheblichen Problemen und Verzögerungen führen kann. Der Mangel an Dokumentation erschwert nicht nur die Fehlerbehebung, sondern beeinträchtigt auch die Weiterentwicklung und Wartung der Software. Eine unzureichende Dokumentation behindert somit den gesamten Softwareentwicklungsprozess und wirkt sich negativ auf die Qualität und die langfristige Wirtschaftlichkeit des Produkts aus. Die Notwendigkeit einer vollständigen und präzisen Dokumentation wird daher als unerlässlich für einen effizienten und erfolgreichen Softwareentwicklungsprozess beschrieben.

Der Abschnitt unterstreicht den positiven Einfluss einer hochwertigen Softwaredokumentation auf die Qualität des Softwareprodukts und den damit verbundenen Wettbewerbsvorteil. Es wird explizit der qualitative Mehrwert betont, der durch eine umfassende Benutzerdokumentation erzielt werden kann. Diese Benutzerdokumentation wird als wichtiger Faktor für die Akzeptanz und den Erfolg des Produkts auf dem Markt hervorgehoben. Die verbesserte Nachvollziehbarkeit des Entwicklungsprozesses und die vereinfachte Fehlerbehebung tragen ebenfalls zum Gesamtwert bei. Durch eine konsistente und gut strukturierte Dokumentation wird nicht nur die Qualität des Endprodukts gesteigert, sondern auch die Effizienz des gesamten Entwicklungsprozesses verbessert. Dies führt zu Zeit- und Kostenersparnissen und stärkt die Wettbewerbsfähigkeit des Unternehmens. Eine umfassende Dokumentation wird also nicht nur als Notwendigkeit, sondern auch als strategischer Vorteil für Unternehmen im Bereich der Softwareentwicklung dargestellt.

Die Planungsphase im Softwareentwicklungsprozess beginnt mit der Projektidee und umfasst Voruntersuchungen zur technischen Machbarkeit und Wirtschaftlichkeit. Ein zentrales Dokument dieser Phase ist die Entwicklungsgenehmigung, die auf Grundlage von Kosten- und Aufwandsplanungen (Kostenplan) sowie einem Organisationsplan (mit Personaleinsatzplan) und Terminplan erstellt wird. Der Dokumentationsplan legt den Umfang und Zeitpunkt der Erstellung weiterer Dokumente fest. Ein Testplan beschreibt die Teststrategie und -umfang für die spätere Software. Der Qualitätsplan definiert die Maßnahmen zur Qualitätssicherung während des gesamten Entwicklungsprozesses. Diese Dokumente bilden die Grundlage für die weitere Entwicklung und sind essentiell für die Steuerung des Projekts. Die wirtschaftlichen Aspekte im Kostenplan spielen eine entscheidende Rolle für die Bewilligung der Entwicklungsgenehmigung.

Die Entwurfsphase gliedert sich in den Fachentwurf und den datenverarbeitungstechnischen Entwurf. Der Fachentwurf beschreibt Funktionen und Daten des Systems und konkretisiert die Anforderungen. Ergebnis sind Daten-, Funktions- und Objektmodelle, die die statische Datenstruktur, Funktionen und deren Beziehungen, sowie die Zusammenfassung von Daten und Funktionen in Objekten darstellen. Der datenverarbeitungstechnische Entwurf baut auf dem Fachentwurf auf und berücksichtigt Hard- und Softwareaspekte sowie die Entwicklungsumgebung. Ergebnisse sind Programmkomponenten, Module und deren Beziehungen sowie deren Aufrufreihenfolge. Diese detaillierte Dokumentation der Entwürfe ist entscheidend für das Verständnis des späteren Systems und ermöglicht eine fundierte Implementierung.

Die Implementierungsphase beinhaltet die Erstellung von Programmabläufen, Benutzeroberflächen sowie die Implementierung und Integration von Komponenten, die in dieser Phase auch getestet werden. Die Abnahmephase umfasst die Überprüfung der Anforderungen aus dem Pflichtenheft und die technische und organisatorische Integration des Produkts. Je nach Umfang sind Schulungen und Betreuung der Benutzer notwendig. Dokumente wie Abnahmeprotokolle und Benutzerunterlagen entstehen in dieser Phase. Schließlich wird die Dokumentation des gesamten Softwareprojekts abgeschlossen. Die Wartung umfasst Fehlerbehebung, Programmänderungen, -erweiterungen und -anpassungen, was wiederum die Aktualisierung der Dokumentation erfordert. Die Dokumentation des Entwicklungsprozesses als Ganzes wird hier als Erfahrungsschatz für zukünftige Projekte hervorgehoben, unterstreicht die Bedeutung eines internen Wissensmanagements.

Die Zuordnung von Dokumenten zu einzelnen Phasen ist oft nicht eindeutig, da sich Anforderungen während des Entwicklungsprozesses ändern. Dies erfordert Anpassungen an der Dokumentation, die häufig vernachlässigt werden, da der Fokus oft auf sichtbaren Bestandteilen des Produkts liegt. Die Verantwortung für die Konsistenz zwischen Software und Dokumentation liegt daher oft bei den Entwicklern. Änderungen an Anforderungen führen regelmäßig zu Anpassungen der Software, während die zugehörige Dokumentation oft nicht entsprechend aktualisiert wird. Dies führt zu Inkonsistenzen und stellt eine häufige Fehlerquelle dar. Die Einhaltung der Konsistenz zwischen Software und Dokumentation ist daher eine zentrale Herausforderung im Softwareentwicklungsprozess und erfordert ein striktes Dokumentenmanagement.

Der Text unterscheidet zwischen zwei Arten von Software-Dokumentation: Programmdokumentation und Prozessdokumentation. Die Programmdokumentation dient primär dem Verständnis der Systeminterna. Sie umfasst die Beschreibung einzelner Programmkomponenten, aller für Betrieb und Nutzung notwendigen Unterlagen und dokumentiert das System selbst. Im externen Umfeld dient sie der Überprüfung von Anforderungen und der Produkteinführung, während sie intern für Weiterentwicklung und Wartung essentiell ist. Im Gegensatz dazu dokumentiert die Prozessdokumentation den Softwareentwicklungsprozess selbst. Sie beinhaltet Informationen über die Projektorganisation und liefert Erfahrungswerte für zukünftige Projekte, z.B. durch Aufwands- und Risikoabschätzungen. Diese Art der Dokumentation dient dem internen Wissensmanagement und ist ein wichtiger Faktor für die Optimierung betriebsinterner Prozesse und die Wettbewerbsfähigkeit des Unternehmens.

Die Anforderungen an die Software-Dokumentation sind vielfältig und hängen von der jeweiligen Zielgruppe ab. Für Systementwickler steht das technische Verständnis von Systeminterna im Vordergrund, während Fachabteilungen andere Anforderungen haben. Für sie müssen Dokumente erstellt werden, die die wesentlichen Eigenschaften der Software verständlich darstellen und Informationen für Marketing und Kundenkontakt liefern. Die Entwicklung der letzten Jahre zeigt einen Wandel von der Fokussierung auf reine Programmierproduktivität hin zu einer ganzheitlichen Betrachtung des Softwareprodukts. Qualitative Ansprüche an die Dokumentation werden immer häufiger Vertragsbestandteil. Dies erfordert eine differenzierte Betrachtung des Softwareprozesses und eine umfassende Dokumentation, da ohne die notwendigen Informationen die Funktionalität und Qualität der Software nicht vollumfänglich nutzbar sind. Die Erfüllung dieser Anforderungen erfordert erhebliche Investitionen in qualifiziertes Personal und eine Neuorientierung der Dokumentenverwaltung.

Der Text erwähnt die Bedeutung von Normen, Standards und Richtlinien für die Software-Dokumentation, die sowohl in internen Qualitätsrichtlinien als auch in Verträgen eine Rolle spielen. Normungsinstitute wie DIN, ISO und IEEE haben branchenübergreifende Vorgaben entwickelt, wobei die DIN 66230 und die DIN EN 62079 (Erstellen von Anleitungen) hervorgehoben werden. Die DIN EN 62079, obwohl primär für technische Dokumentationen entwickelt, findet auch Anwendung in der Softwareentwicklung. Neben diesen übergreifenden Standards existieren zahlreiche betriebsspezifische Dokumente und Muster, die zusätzliche Aspekte wie strukturelle und visuelle Anforderungen konkretisieren. Die ISO 9001-Zertifizierung wird als weiterer Aspekt für die Durchsetzung und Akzeptanz von Qualitätsstandards erwähnt, obwohl der Fokus der Norm auf Prozessverbesserung und Kundennutzen liegt. Die korrekte Erfassung und Untergliederung von Anforderungen erfolgt über 26 Kategorien in vier Bereichen, die eine spätere Analyse des Entwicklungsprozesses und die Identifikation von Fehlern ermöglichen.

Der Text hebt die Bedeutung von XML als Datenformat und -austauschformat für die Software-Dokumentation hervor. XML wird aufgrund seiner Fähigkeit zur Strukturierung von Informationen und seiner Plattformunabhängigkeit als Lösung für die Dokumentenverwaltung präsentiert. XML ermöglicht die Erstellung eigener, spezifisch ausgerichteter, struktureller Aufbauten zur Datenbeschreibung, wodurch es als umfassende Datenquelle dient, die sowohl plattformübergreifend als auch von der jeweiligen Anwendung unabhängig ist. Die Anwendungsidee (Dokumente, Datensätze, Transaktionsdaten) spielt dabei aus technischer Sicht keine Rolle. Daten können ihrem Verwendungszweck entsprechend generiert und aufbereitet werden. XML wird als Basis für die Übernahme und Beschreibung von Datenstrukturen verschiedenster Formate und den Datenaustausch verschiedener Anwendungen vorgestellt. DocBook, ein XML-basiertes Format, wird als Beispiel für eine definierte Struktur im Bereich technischer Dokumentation genannt. Der Text hebt die Vorteile von XML bezüglich der Strukturierung von Informationen und deren spätere Weiterverarbeitung hervor.

TeX und LaTeX werden als etablierte Standards im Bereich umfangreicher, wissenschaftlicher Publikationen beschrieben, obwohl auch hier Alternativen entstehen. LaTeX wird als Werkzeug zur Übersetzung der logischen Struktur eines Textes in TeX dargestellt, das die Handhabung von TeX vereinfacht. Im Gegensatz zu TeX, das über 900 Befehle umfasst, vereinfacht LaTeX die Arbeit durch Makro-Pakete und verringert den Bedarf an Kenntnissen über Satztechniken und Layout-Stile. Der Text stellt TeX als leistungsstarkes System zur Darstellung von Formeln und grafischen Elementen dar, das jedoch eine umfassende Einarbeitung erfordert. Ein Vergleich zu Word, einem WYSIWYG-Editor, verdeutlicht die Unterschiede zwischen direkter visueller Gestaltung und der strukturorientierten Texterstellung in TeX/LaTeX. Word bietet Vorteile durch seine einfache Bedienung und Integration in Softwarepakete, während TeX/LaTeX für die professionelle Erstellung von Dokumenten mit fester Struktur und Typografie eingesetzt wird, jedoch eine höhere Einarbeitungszeit benötigt.

XSLT wird als Technologie zur Transformation von XML-Daten in neue Strukturen oder Texte beschrieben. XSL-FO ermöglicht die visuelle Aufbereitung der Daten, indem Seitenaufbau und Layout definiert werden. Mit über 50 Elementen, die baumartig angeordnet sind, wird die Formatierungssemantik hinzugefügt. Ein XSLT-Prozessor ist notwendig, um aus der XML-Hierarchie einen Ergebnisbaum zu generieren. Die Kombination von XML, XSLT und XSL-FO ermöglicht eine effiziente Verarbeitung und Aufbereitung von Daten für verschiedene Ausgabeformate. Der Text betont die Vorteile von XSLT für die Transformation von XML-Daten in andere Formate, die für verschiedene Zwecke genutzt werden können, wie beispielsweise die Konvertierung von DocBook oder anderen XML-Formaten in TeX mittels Stylesheets. Jedoch bleibt die Notwendigkeit von TeX-Kenntnissen für Formatierung und Layout bestehen.

Doxygen wird als Anwendung vorgestellt, die die automatisierte Datenauswertung aus Quellcode ermöglicht. Es sucht gezielt nach Schlüsselwörtern und wertet Kommentare im Programmcode aus, um Informationen zu extrahieren. Doxygen unterstützt verschiedene Programmiersprachen (Java, C, C++, IDL) und generiert diverse Formate (HTTP, XML, RTF, TEX, PostScript, PDF, UNIX Man Pages). Der Vorteil liegt in der großen Auswahl an generierbaren Formaten, jedoch integriert Doxygen weitgehend eigene Layouts. Es können zusätzlich Abhängigkeits-, Vererbungs- und Kollaborationsdiagramme erzeugt werden. Der Text weist darauf hin, dass Doxygen zwar Programmbestandteile wie typedef und Funktionen erkennt, die Bedeutung und der Zweck der Funktionen jedoch nur durch zusätzliche Kommentare im Quellcode erschlossen werden können. Parser-spezifische Anweisungen sind in den Kommentaren notwendig.

Der Abschnitt beschreibt einen Lösungsansatz zur Automatisierung der Software-Dokumentation, der auf der Nutzung aktueller Technologien basiert. Das Ziel ist die Erleichterung der oft aufwendigen und unbeliebten Aufgabe der Dokumentenerstellung. Die Automatisierung soll Softwareentwickler, insbesondere in kleinen und mittelständischen Unternehmen, entlasten und die Qualität anderer Aufgabenbereiche verbessern. Für größere Softwareprojekte bietet die Automatisierung eine Entlastung in den Bereichen Kommunikation und Fehleranfälligkeit. Der Ansatz beinhaltet die Nutzung von Quellcode-Parsern (z.B. Doxygen) zur Extraktion von Informationen aus dem Quellcode und deren Überführung in ein Datenübertragungsformat wie XML. Dies bildet die Grundlage für eine automatisierte Weiterverarbeitung und die Erstellung einer Datenbasis, die den Entwicklungsprozess dokumentiert. Die Überführung in XML ermöglicht einen universellen Datenaustausch für verschiedene Zwecke. XML wird als strukturierendes Element für eine effiziente Dokumentenverwaltung angesehen.

Der Einsatz von XML wird aufgrund seiner Eigenschaften zur Strukturierung von Informationen und seiner Rolle als Datenquelle und Austauschformat begründet. Die Analyse der verwendeten Datenformate im Unternehmen ist dabei ein wichtiger Schritt. XML wird bevorzugt, da es sowohl als Datenquelle als auch als Austauschformat fungieren kann. Die einheitliche Struktur und die vielfältigen Aufbereitungsmöglichkeiten sprechen für seinen Einsatz. Jedoch ist mit der Verwendung von XML ein erheblicher Aufwand an Erfassung und Umwandlung verbunden. Die Notwendigkeit einer einheitlichen Struktur, die durch eine DTD (Document Type Definition) sichergestellt wird, wird betont. Die anschließende Transformation der XML-Daten erfolgt mit XSLT (eXtensible Stylesheet Language Transformations) in ein Textsystem (z.B. TeX), um eine abschließende Bearbeitung und Einflussnahme auf die Informationen zu ermöglichen. Die Wahl von TeX als Zwischenformat wird damit begründet, dass die Daten nur in eine andere ASCII-Form umgewandelt werden müssen und der Aufwand begrenzt bleibt.

Als Textsystem wird TeX gewählt, da es die Daten nur in eine andere ASCII-Form umwandeln muss, und der Aufwand somit gering bleibt. Um eine sinnvolle Bearbeitung in TeX zu gewährleisten, werden dem Text eigene Anweisungen und Umgebungen hinzugefügt, die das Layout definieren. Es wird vorgeschlagen, eigene Stylesheets zu erstellen, um eine gleichbleibende Qualität zu gewährleisten und den Bedarf an Kenntnissen im Umgang mit dem generierten Format zu minimieren. Das Ziel ist, möglichst viele Informationen aus dem Quellcode in ein Textformat zu überführen, um die Mitarbeiter zu entlasten und die Daten in einer sinnvoll strukturierten Form aufzubereiten. Die Nutzung von selbstdefinierten Umgebungen in LaTeX ermöglicht eine eindeutige Strukturierung und vereinfacht die Bearbeitung, wobei die Vollständigkeit und Richtigkeit der Informationen im Vordergrund steht. Abschließend wird das TeX-Format in das PDF-Format konvertiert, das als geeignetes Publikationsformat gilt.

Der Abschnitt fasst die Ergebnisse zusammen und benennt die Grenzen der Automatisierung. Es zeigt sich, dass zwar sinnvolle Ansätze existieren, die Automatisierung des Quellcodes jedoch Grenzen aufweist. Das selbstständige Erkennen von Programmbestandteilen reicht für eine qualitativ hochwertige Dokumentation nicht aus. Zusammenhänge zwischen Programmbestandteilen und die Ziele des Programms müssen manuell mit einem Textsystem hinzugefügt werden. Referenzdokumentationen, die vorrangig Programmbestandteile auflisten, sind jedoch möglich. Die Arbeitserleichterung durch die Nutzung aktueller Technologien wie XML und XSLT wird hervorgehoben, besonders für Softwareentwickler in kleinen und mittleren Unternehmen. Die Nachvollziehbarkeit des Softwareentwicklungsprozesses durch eine projektorientierte Dokumentenverwaltung wird als weiterer Vorteil genannt, der Ansätze zur Produkt- und Prozessverbesserung ermöglicht.