Benutzerdokumentation automatisiert generieren
01. Mai. 2022
Softwareentwicklung neu gedacht
Die agile Softwareentwicklung hat sich in den letzten Jahren zu einem wichtigen Ansatz der technischen Umsetzbarkeit entfaltet. Neben den Vorteilen, wie z. B. Flexibilität, Fehlererkennung und erhöhte Performanz durch eine stetige Kommunikation, bringt eine agile Softwareentwicklung jedoch auch Einschränkungen mit sich.
So wird die Dokumentation - zu welcher auch die Benutzerdokumentation zählt - eher relativiert betrachtet und zugunsten der engen Zusammenarbeit zwischen Entwickler:innen, Tester:innen, Kund:innen und Nutzer:innen auf ein Minimum beschränkt.
Bedingt durch Covid-19 musste der persönliche Kontakt mit Kunden, welcher in einer agilen Entwicklungsumgebung einen hohen Stellenwert besitzt, auf ein Minimum reduziert werden. Dabei gewann Software allgemein in den letzten Jahren immer mehr an Komplexität, welches auch eine zunehmende Rolle in der Organisation von Informationen innerhalb der Benutzerdokumentation zur Folge hat.
Zudem unterliegen Softwaresysteme während ihres gesamten Lebenszyklusses ständigen Veränderungen und die Informationsmenge wächst kontinuierlich. Gerade in der besagten, agilen Entwicklungsumgebung, wo in vielen Iterationsschritten und in enger Zusammenarbeit mit dem Kunden immer wieder neue Software-Versionen veröffentlicht werden, sind häufige Änderungen innerhalb der Software keine Seltenheit. Um die Bedienbarkeit der Software sicherzustellen und zu verbessern, eignet sich die Benutzerdokumentation - eine manuelle Erstellung der Benutzerdokumentation kann jedoch recht viel Zeit in Anspruch nehmen, da diese nach jedem Release neu erstellt werden müsste.
Um eine optimale Alternative zu schaffen, wurde daher ein Tool programmiert, welches die Benutzerdokumentation in Relation zu einem Projekt automatisiert generieren kann.
Entwicklung des Softwaretools
Im ersten Schritt wurde die Software konzipiert - hier mussten im Vorfeld die allgemeinen Grundlagen der Benutzerdokumentation geklärt werden, um ein fundamentales Verständnis diesbezüglich aufzubauen. Diese betreffen die existierenden Normen und Standards der Normenreihe IEEE /ISO/IEC 26511-26515, welche hinsichtlich der Erstellung von Benutzerdokumentation für Software die Maßstäbe und Richtwerte vorgeben. Darüber hinaus wurden die verschiedenen Arten der Benutzerdokumentation beleuchtet.
Im Anschluss an die Anforderungsanalyse erfolgte dann der Softwareentwurf. Für den Softwareentwurf musste zunächst die Terminologie abgehandelt werden, da für diesen die Herangehensweise Domain-Driven Design in Verbindung mit der Hexagonalen Architektur angewandt wurde. Durch den Einsatz dieser Herangehensweisen in der Modellierung entsteht ein modulares System, welches die Fachlichkeit in den Vordergrund stellt und ein hohes Maß an Testbarkeit bereitstellt.
Die Hexagonale Architektur nach Alistair Cockburn gibt dabei die drei Schichten Domain-Layer, Application-Layer und Ports vor:
- Innerhalb der Domain-Layer befindet sich das Domain Model, welches die gesamte Geschäftslogik in Form von verschiedenen Entities, Value Objects und Aggregates speichert. Die Inhalte der Domain-Layer sind dabei unabhängig von anderen umliegenden Komponenten.
- Die Application-Layer umgibt die Domain-Layer und ist für die Verwaltung der Objekte im Domain Model zuständig. Darüber hinaus beinhaltet diese Schicht alles Nötige für die Infrastruktur - beispielsweise die Anbindung von externen technischen Frameworks. Die Application-Layer nutzt zur Kommunikation mit der Außenwelt dedizierte Schnittstellen, welche als Port bezeichnet werden.
- Die Ports übersetzen dabei die Befehle bzw. die Informationen, die von außen in die Softwareanwendung einfließen, auf die interne Fachlogik. Die Abhängigkeiten laufen also immer von außen nach innen.
Schichtenstruktur und zugehörige Abhängigkeiten
Ablauf - Implementierung der Software
Im ersten Sprint ging es darum, das aufgestellte Konzept anzuwenden und die Grundstrukturen des Projektes anzulegen. Zudem wurden diverse Adapter-Module gemockt, welche das entsprechende Modulverhalten simulieren.
Der zweite Sprint beschäftigte sich mit der Aufnahme der Screenshots. Die Screenshots werden hierbei mittels des Tools Selenium WebDriver aufgenommen und anschließend für die weitere Verwendung gespeichert.
Im dritten Sprint wurde die Funktionalität des Overlays implementiert. Hierzu wurden die zuvor aufgenommenen Screenshots manipuliert, um dem Nutzer zusätzlich kontextbezogene Informationen auf den Screenshots liefern zu können.
Der vierte und letzte Sprint beschäftigte sich mit der Erstellung des finalen PDF-Dokumentes, welches nach Einpflegen aller wichtigen Informationen im Zielordner ausgegeben wird. Die Informationen werden dabei in Kapiteln angelegt.
Bewertung der Benutzerdokumentation als lohnende Alternative
Um abschließend bewerten zu können, ob das entwickelte Hilfsmittel zur automatisierten Generierung von Benutzerdokumentation eine lohnende Alternative zu einer händisch erstellten Benutzerdokumentation ist, wurden die Meinungen der Projektmanager bei uns eingeholt.
Der Initialaufwand für solch eine automatisierte Lösung ist sehr hoch. Ist dieser aber erst mal bewältigt, bringt die automatisierte Lösung einen immensen Zeitvorteil gegenüber der händisch erstellten Benutzerdokumentation.
