Erstellen Sie Ihre Softwaredokumentation auf Knopfdruck

Jeder Programmierer braucht eine zuverlässige Softwaredokumentation für seine Arbeit. Die meisten Softwareentwickler arbeiten zeitgleich an mehreren Programmen. Daher ist es besonders wichtig, eine gute Softwaredokumentation zu pflegen, um alle Schritte in der Entwicklung der verschiedenen Programme nachvollziehen zu können. Ganz nebenbei hilft eine gute Softwaredokumentation bei der späteren Wartung und Weiterentwicklung der Software. Sie hilft auch anderen Entwicklern dabei, sich in für sie fremde Programme einzuarbeiten.

Als Softwareentwickler habe ich selbst oft gesehen, dass viele Programmierer zwar durchaus wissen, dass eine saubere und vollständige Softwaredokumentation nötig ist, doch für viele ist das Thema ein Reizwort. Es ist ja auch eine aufwändige und zeitraubende Arbeit, die ganzen Screenshots zu machen und jeden Entwicklungsschritt detailgenau aufzuschreiben.

Besonders im regulierten Umfeld (z. B. Pharma, Medizintechnik) ist eine lückenlose Dokumentation aller Eigenentwicklungen Grundvoraussetzung für deren Produktivsetzung. Doch das ist nicht der einzige Grund, warum ein Unternehmen Interesse an einer guten Softwaredokumentation haben sollte.

Warum ist Softwaredokumentation überhaupt nötig?

IT-Compliance und Wirtschaftsprüfer stellen höchste Anforderungen an Softwaredokumentationen. Auch IT-Verantwortliche sollten ein hohes Interesse an der korrekten und vollständigen Dokumentation von Eigenentwicklungen haben. Sonst ist das Wissen nicht zentral verfügbar, sondern exisitiert als so genanntes Herrschaftswissen nur in den Köpfen der Entwickler. Das schafft Abhängigkeiten, die erhebliche Probleme verursachen können, wenn der Entwickler irgendwann das Unternehmen verlassen sollte.

Softwaredokumentation: intern oder extern?

SAP bietet die Möglichkeit, Dictionary-Objekte direkt im System zu dokumentieren, doch davon wird in der Praxis wenig Gebrauch gemacht. Das liegt daran, dass diese Methode nur eine sogenannte interne Softwaredokumentation ermöglicht, so dass zusätzlich eine systemexterne Dokumentation z. B. in Microsoft Word erforderlich ist, damit alle Informationen an einer Stelle verfügbar sind. Die meisten Programmierer, die ich gefragt habe, scheuen diesen Doppelaufwand verständlicherweise. Daher dokumentieren sie in der Regel entweder nur in SAP oder nur in einem externen Dokument – oder im schlimmsten Falle gar nicht.

Geht es nicht auch ohne Softwaredokumentation?

Denken Sie daran: eine fehlende Softwaredokumentation kann große Risiken für Ihr Unternehmen nach sich ziehen.  Das betrifft die Wartungsfreundlichkeit, die Qualitätskontrolle und die Weiterentwicklung der Software, ganz zu schweigen von dem am Anfang des Beitrags schon erwähnten Know-how Transfer, der ohne Softwaredokumentation sehr schwierig wird. Ohne Softwaredokumentation können Ihre Programmierer nicht alle Entwicklungsschritte im Auge behalten. Im schlimmsten Fall führt das dazu , dass sie später „das Rad neu erfinden“ müssen.

Sie erkennen Ihre Firma hier wieder? Dann gebe ich Ihnen jetzt ein paar Tipps, wie Sie diese Stolperfallen vermeiden können.

Warum interne UND externe Dokumentation?

Gibt es für eine neue Software überhaupt keine Softwaredokumentation, ist es für einen Dritten nur mit sehr hohem Aufwand möglich, sich in die technischen Aspekte und die Logik des Programms einzuarbeiten. Wenn Sie nun die technischen Geheimnisse des Programms verstehen wollen, geht das nur über ein umständliches „Reverse Engineering“, also den Versuch, durch Analyse des Codings auf die Zusammenhänge zurückzuschließen. Bei komplexen Programmen ist der Aufwand dafür so hoch, dass eine komplette Neuentwicklung häufig billiger ist.

Eine rein systeminterne Dokumentation macht es einem Externen (z. B. Prüfer) schwer, sich schnell einen Überblick über die Bestandteile des Programms und seiner Dokumentation zu verschaffen. Daher ist in der Regel ein zentral verfügbares, externes Dokument verpflichtend.

Wird nur systemextern dokumentiert, so bietet ein Word-Dokument einen guten Überblick und kann ein schneller Einstieg in das Verständnis eines Programms/Programmteils sein. Trotzdem ist die Dokumentation innerhalb des Systems gerade bei der Analyse des Codings sehr nützlich. Denn damit stehen die Details zur Architektur und Entwicklung jedes Programmteils zur Verfügung, so dass Entwickler den bestehenden Code schnell nachvollziehen und jederzeit wieder aufgreifen können.

Meiner Meinung nach wäre es also das ideale Szenario eine systeminterne Dokumentation, die zusätzlich in einem zentralen externen Dokument mitgeschrieben wird. Dies ist aber sehr aufwändig.

Was wäre, wenn die Softwaredokumentation automatisch erstellt werden könnte?

Sie sagen, das geht nicht? Ich sage: Es geht doch! Und zwar mit dem von mir und meinem Kollegen Jörg Hofmann entwickelten SAP ABAP Dokumentationsgenerator. Mit ihm können Sie automatisch eine technische Dokumentation zu SAP ABAP/ABAP-OO-Entwicklungen erstellen.

So funktioniert es

Wenn Sie mit dem Dokumentationsgenerator arbeiten, geben Sie zuerst ein komplettes Entwicklungspaket, einen Transportauftrag oder einzelne Objekte an. Das Programm ermittelt dann alle Repository-Objekte, die zu dieser Entwicklung gehören. Im Customizing können Sie einstellen, welche Objekte berücksichtigt werden. Nun gibt der Generator eine Inventarliste aller Objekte in einem editierbaren Word oder Word-XML-Template aus.

Normalerweise brauchen Sie für das manuelle Erstellen einer solchen Dokumentation bei komplexen Projekten ein bis zwei Tage. Der Dokumentationsgenerator löst diese Aufgabe in wenigen Minuten.

Wenn Sie die Objekte direkt in SAP über Langtexte dokumentiert haben, so kann diese Dokumentation ebenfalls nach Word übertragen werden. Somit müssen Sie nur einmal dokumentieren, und zwar direkt im SAP System und sparen so richtig viel Zeit. Die externe technische Dokumentation erstellt der Dokumentationsgenerator auf Knopfdruck.

Damit ist auch gewährleistet, dass interne und externe Dokumentationen stets auf dem gleichen Stand und zentral verfügbar sind.

Wir bei PIKON setzen dieses nützliche Tool bislang auch selbst in eigenen Entwicklungsprojekten ein, um unseren Kunden unmittelbar nach Abschluss des Projekts eine vollständige technische Dokumentation zu liefern.

Sie möchten mehr über den Dokumentationsgenerator und seine Möglichkeiten erfahren? Sie wollen mir zu diesem Thema etwas mitteilen? Dann nutzen Sie die Kommentarfunktion unseres Blogs – ich diskutiere gerne mit Ihnen.

Sie möchten mehr erfahren?

Auf unserer Webseite finden Sie weitere Informationen zum Thema SAP ABAP Dokumentationsgenerator. Dort stellen wir Ihnen auch gerne eine freie Testversion zur Verfügung, damit Sie selbst sehen können, wie einfach Softwaredokumentation mit diesem Tool ist.

Bildnachweise

Titelbild: Fotolia Nr. 99956429, @ kavzov

Teilen Sie diesen Beitrag