One Identity

Dokumentations Generator

Lassen Sie sich automatisch eine anwendertaugliche Systemdokumentation Ihrer One Identity Umgebung erzeugen. Die Dokumentation kann anschließend als eigenständige Webseite bereitgestellt werden oder als Confluence Wiki Bereich mit zustätzlichen Features (Suche, Verknüpfungen, …).

Interesse geweckt?

Kontaktieren Sie uns gleich hier!

Dokumentation ist ein zentraler Bestandteil für den Betrieb einer Anwendung. Sei es für das Einarbeiten neuer Mitarbeiter oder für das Nachvollziehen von implementierter Programmlogik. Obwohl viele Mitarbeiter gerne eine gut geschriebene Dokumentation lesen, wird deren Erstellung als langweilige und unangenehme Aufgabe gesehen. Dies liegt unter anderem daran, dass Dokumentation häufig auf die folgenden zwei Arten erstellt wird:

  1. Dokumentation wird in Word/Wiki/Sharepoint/etc. seperat vorgehalten
    Durch die Nutzung der jeweiligen Dokumentenplattform lassen sich gut strukturierte Dokumentation erstellen, welche recht einfach vielen zugänglich gemacht werden kann. Jedoch muss darauf geachtet werden, dass bei Änderungen am System auch die Dokumentation angepasst wird. Häufig laufen Programmlogik und Dokumentationen schnell auseinander.
  2. Dokumentation wird direkt am Code vorgehalten
    Durch die starke nähe zum Code ist es recht einfach die Dokumentation bei stetiger Entwicklung aktuell zu halten. Leider ist die Dokumentation damit oft selber Teil des Programmcodes, was einerseits das aufbereiten selbiger stark einschränkt (nur Text) und den Zugriff auf das Entwicklungsteam beschränkt.

Unsere Lösung!

Der Dokumentations-Generator verbindet beide Ansätze und kombiniert deren Vorteile.

Das System ist die Quelle

Als Datenquelle für die Dokumentation wird das System selber verwendet. Dabei werden alle notwendigen Daten extrahiert und anschließend aufbereitet.

Durch die Verwendung der an vielen Stellen vorhandenen Beschriebungsfelder innerhalb des Systems wird die Dokumentation direkt an den Stellen durchgeführt, an denen auch die Entwicklung stattfindet. So können Entwickler an neuen oder geänderten Objekten angeben, wozu diese benötigt werden pder deren Einsatz anwendertauglich zusammenfassen.

Des Weiteren kann bei der Extraktion der Daten exakt eingestellt werden, welche Daten aus dem System für die Dokumentation ausgelesen und somit bereit gestellt werden. Die Leser erhalten so nur für sie relevante Informationen.

Dokumentation als Website

Die aus dem System extrahierten Daten werden als Website aufbereitet. Dabei werden nicht nur die Informationen als reiner Text dargestellt, sondern auch intelligent mit einander Verknüpft. Dadurch ist es nur nur eine Ansammlung von einzelnen Seiten, sondern eine hierarchisch Dokumentation mit Querverweisen auf andere relevante Objekte/Seiten

 

Die so erstellten Seiten können anschließend jeden Mitarbeiter zur Verfügung gestellt werden. Es muss kein Zugriff auf den Code des Systems eingerichtet werden.

Diff-Darstellung von geänderten Code

Neben den Informationen, welche Programmlogik das System ausführt, ist häufig auch relevant, welche vom Hersteller mitgelieferten Komponenten angepasst wurden. 

Hierzu wird der aktuelle Programmcode mit dem vom Hersteller abgeglichen und eine Diff-Ansicht erstellt. Codezeilen, die ausgehend vom Hersteller entfernt wurden werden rot dargestellt und hinzugefügte Codezeilen grün.

Aufbereitung von Code-Kommentaren

Damit Programmcode nicht nur von entsprechenden Entwicklern gelesen und verstanden werden können, findet eine spezielle Aufbereitung von Code-Kommentaren statt. Der Dokumentation-Generator unterstützt die XML-Kommentare für C#/VB.NET und bereitet diese für die generierte Dokumentation auf.

Dadurch ermöglichen wir den Entwicklern direkt am Programmcode die Dokumentation zu hinterlegen, welche anschließend anderen Mitarbeitern in einer lesbaren Form zur Verfügung gestellt wird. So wird es extrem einfach die Anwenderdokumentation stehts aktuell zu halten.

Beispiele der Aufbereitung von Code-Kommentare

Zum Sehen der Code-Kommentar mit der Maus über die jeweilige Grafik gehen.

Bereitstellung über Confluence inkl. Revisions

Die Dokumentation kann neben einer einfachen Website auch als Confluence Wiki bereitgestellt werden. Neben den oben beschriebenen, ebenfalls vorhandenen Features, bietet die Verwendung von Confluence weitere Vorteile.

Seitenhistorie

Das Confluence Wiki bietet Out-of-the-box die Anlage von Seitenhistorien. Ändert sich bei einer erneuten Generierung der Dokumentation der Inhalt einer Seite, so wird die korrespondierende Wiki-Seite ebenfalls aktualisiert und es entsteht eine neue Seitenrevision. Über die Ansicht der Seitenhistorie lassen sich so Änderungen an der Dokumentation und somit auch an dem System einfach erkennen und nachvollziehen.

Integrierte Suche

Die integrierte Suche ermöglicht das einfache und zielgenaue Durchsuchen der erstellten Dokumentation. Ob Objektname oder Code-Fragment – jeder bereitgestellte Inhalt kann durchsucht werden.

Integration in handgeschriebene Dokumentation

Bei allen Seiten wird der Kopfteil mit dem Makros Auszug versehen. Mit dem korrespondierenden Marko Auszug einschließen lässt sich dieser Bereich nun in ein andere Seite einbetten. Dies ermöglicht die Integration der generierten Dokumentation mit einer Selbstgeschriebenen. So können Sie Aufwand für das doppelte Beschreiben von Informationen vermeiden und erhöhen gleichzeitig die Qualität ihrer Dokumentation. 

Sobald eine generierte Seite aktualisiert wird, wird auch deren Einbettung automatisch aktualisiert.

Interesse geweckt?

Kontaktieren Sie uns gerne über kontakt@inoteq.com.