Benutzerdokumentation automatisiert generieren

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

1

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.

2

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.

3

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.

4

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.

Weitere Blogartikel

23. Jun. 2022

Simulierte Netzwerktests

Blog

Mobiles Internet für alle – vor 20 Jahren noch eine weit entfernte Vision, heute bereits Realität. 86% der Deutschen besitzen laut einer aktuellen [Statistik](https://de.statista.com/statistik/daten/studie/585883/umfrage/anteil-der-smartphone-nutzer-in-deutschland/) heutzutage bereits ein internetfähiges Smartphone, Tendenz steigend. Gleichzeitig bildet Deutschland jedoch das Schlusslicht Europas wenn es um das Thema Netzausbau geht – nur 65% des Landes wird mit einem 4G Netz abgedeckt, 2% weniger als in Albanien und 24% hinter den Niederlanden, siehe aktuelle [Analysen](https://www.opensignal.com/reports/2018/02/state-of-lte). Diese Diskrepanz führt zu einem beinnahe alltäglichen Problem in der mobilen Anwendungsentwicklung. Nahezu jede Anwendung besitzt heutzutage Funktionalitäten, die eine Internetverbindung benötigen. Dabei gehört es grundsätzlich zu den Anforderungen an ein Softwaresystem, dass dieses unter allen sich ihm bietenden Netzwerkbedingungen stabil, oder zumindest vorhersagbar agiert. mehr

28. Apr. 2022

Empathy Maps als UX-Tool

Headerbild Empathy Maps
Blog

In Entwicklungs-, Design- oder Marketing-Teams bestehen oftmals unterschiedliche Vorstellungen von Zielgruppen, bzw. dem Endnutzer einer Applikation. Dies kann dann problematisch werden, wenn bspw. neue Features geplant oder versucht wird, den Endnutzer in Texten sowie Bildern direkt anzusprechen. Vor allem aber führt dies oftmals zu langwierigen Prozessen sowie Entscheidungen über die Nutzer und deren Bedürfnisse. Um dieser Herausforderung entgegenzuwirken, lassen sich unterschiedliche Ansätze sowie Methoden nutzen. Eine besonders effiziente und in der Umsetzung einfache Methode ist die „Empathy Map“. Empathy Maps sind ein agiles Tool im Bereich des User Experience Designs, das dabei hilft, die Nutzer sowie deren Bedürfnisse besser zu verstehen und ein einheitliches Mindset im Projekt-Team zu etablieren. Die Nielsen Norman Group, eine Erfolgreiche UX Beratungsfirma aus Amerika, welche von den User Experience Pionieren, Don Norman und Jakob Nielsen gegründet wurde, definiert Empathy Maps wie folgt: mehr

15. Apr. 2022

Flexibel einsetzbare Markupsprache

Blog

Die Idee, dass Daten wertvoll sind und das strukturierte Speichern dieser sinnvoll ist, wurde schon in den 60er Jahren im Konzept des Generic Coding erkannt. Diese Versuche, eine vereinheitlichte Sprache zur Beschreibung von Daten zu entwickeln, mündeten 1986 in die Entstehung der Standard Generalized Markup Language (SGML), welche sich durch die Verwendung von sogenannten Tags auszeichnet. Die Ähnlichkeit zu modernen Markup-Sprachen wie HTML oder XML ist kein Zufall, da diese SGML-konform entstanden sind, sich aber mittlerweile davon gelöst haben, um ihre Struktur weniger eingeschränkt anpassen zu können. mehr

17. Mär. 2022

Wohin mit all den Daten?

Blog

Kennen Sie es auch? Sie wollen in Ihrem Unternehmen auf bestimmte Daten zugreifen, können diese aber auf die Schnelle nicht finden – einige liegen auf den Rechnern der Mitarbeitenden, andere auf Datenbanken oder in der Cloud und wieder andere innerhalb von Softwaresystemen. Sie fragen sich, ob es nicht eine Möglichkeit gibt, all’ diese Daten ohne einen großen Aufwand zu sammeln und von einem Ort aus nutzen zu können? Die Antwort ist: Ja! Die Digitalisierung von Unternehmen ist in vollem Gange: Prozesse werden optimiert und automatisiert, Kommunikation wird dynamischer und die generelle Effizienz von Unternehmen steigert sich. Die mit der digitalen Transformation einhergehenden, gewaltigen Datenmengen – Stichwort Big Data – können genutzt werden, um Datenanalysen durchzuführen, die hochwertige Erkenntnisse für das eigene Unternehmen generieren können. Aber wo soll man nun beginnen? Daten innerhalb des eigenen Unternehmens sind oftmals weitläufig verteilt, nicht zwangsläufig strukturiert und haben unterschiedliche Dateiformate. Die Nutzung einer geeigneten Infrastruktur, die die Daten automatisiert extrahiert und speichert, stellt die Basis für eine organisierte Datenhaltung dar, die anschließende Auswertungen und Analysen ermöglicht. mehr