DokumentationProjekte nachhaltig zum Leben bringen

Ausgangslage

Während der Umsetzung eines technischen Projekts entsteht eine Vielzahl relevanter Informationen. Dazu gehören Hinweise zur Bedienung, Funktionsbeschreibungen, Datenquellen, Schnittstellen, technische Abläufe, Abhängigkeiten und projektspezifische Einstellungen.

Diese Informationen sind häufig über verschiedene Dateien, E-Mails, Besprechungsnotizen oder den Quellcode verteilt. Nach Abschluss des Projekts fehlt dadurch oft eine zentrale Stelle, an der die Funktionsweise der Lösung vollständig und verständlich beschrieben wird.

Dies erschwert insbesondere die spätere Nutzung, Übergabe oder Weiterentwicklung. Neue Mitarbeitende oder nicht direkt am Projekt beteiligte Personen müssen sich zunächst in unterschiedliche Quellen einarbeiten. Bei technischen Änderungen müssen bestehende Zusammenhänge teilweise erneut analysiert werden.

Auch klassische Dokumentationen sind nicht immer dauerhaft nutzbar. Sie bestehen häufig aus mehreren Dateien, extern eingebundenen Bildern oder Verlinkungen auf Webseiten und Ablageorte. Werden Dateien verschoben, Ordnerstrukturen verändert oder Webseiten abgeschaltet, können einzelne Bestandteile der Dokumentation nicht mehr richtig angezeigt werden.

Zusätzlich sind viele Dokumentationsformate nicht optimal für die Verwendung durch einen Chatbot oder ein KI-System geeignet. Komplexe Formatierungen, umfangreiche Layoutinformationen und unnötige Wiederholungen erschweren die Verarbeitung und erhöhen den Tokenverbrauch.

Benötigt wird daher eine technische Projektdokumentation, die einfach geöffnet, geteilt und archiviert werden kann. Gleichzeitig soll sie so strukturiert sein, dass die enthaltenen Informationen effizient durch einen projektbezogenen Chatbot genutzt werden können.

Definierte Lösung

Die Dokumentation wird individuell auf die entwickelte Lösung abgestimmt. Sie beschreibt die Anwendung aus Sicht der Nutzerinnen und Nutzer und dokumentiert gleichzeitig die technischen Zusammenhänge, die für Betrieb, Anpassung und Weiterentwicklung erforderlich sind.

Je nach Projekt enthält sie unter anderem:

• den Aufbau und die Bedienung der entwickelten Lösung,

• die Beschreibung der wichtigsten Funktionen,

• typische Nutzungsschritte und Anwendungsfälle,

• verwendete Datenquellen und Eingaben,

• die Verarbeitung und Zusammenführung der Daten,

• Schnittstellen zu anderen Systemen,

• automatisierte Abläufe und Aktualisierungsprozesse,

• technische Voraussetzungen und Abhängigkeiten,

• relevante Einstellungen und Konfigurationen,

• bekannte Einschränkungen und Fehlerbilder,

• Hinweise zu Betrieb, Wartung und Weiterentwicklung.

Aus diesen Inhalten werden zwei unterschiedliche Dokumentationsformate erstellt.

Das erste Ergebnis ist ein eigenständiges HTML-Dokument. Dieses enthält die vollständige visuelle Projektdokumentation einschließlich Navigation, Texten, Tabellen, Bildern, Codebeispielen und Projektinformationen.

Alle für die Darstellung erforderlichen Inhalte werden direkt in die HTML-Datei eingebunden. Die Dokumentation benötigt dadurch keine zusätzliche Ordnerstruktur, keine externe Bildablage und keine öffentlich erreichbare Webseite.

Der Kunde muss lediglich die HTML-Datei öffnen. Die Dokumentation wird anschließend direkt in einem aktuellen Browser dargestellt. Es ist keine Installation und keine besondere Dokumentationssoftware erforderlich.

Die Dokumentation wird als lokal gespeicherte Datei bereitgestellt. Im Gegensatz zu einer öffentlich erreichbaren Webseite ist sie nicht automatisch über das Internet zugänglich. Sicherheitstechnisch lässt sie sich mit einer Word- oder PDF-Datei vergleichen: Solange der Kunde die Datei nicht weitergibt, hochlädt oder in einer gemeinsam zugänglichen Ablage speichert, erhalten andere Personen keinen Zugriff darauf.

Die Datei kann lokal gespeichert, archiviert, per E-Mail versendet oder gezielt über eine interne Dateiablage geteilt werden. Der Kunde entscheidet damit selbst, wer Zugriff auf die Dokumentation erhält. Da alle Inhalte in einer einzigen Datei enthalten sind, bleiben Texte, Bilder, Navigation und Gestaltung auch bei einer Weitergabe vollständig erhalten.

Dasselbe gilt für die zusätzlich bereitgestellte Markdown-Datei für den Chatbot. Auch sie ist zunächst eine lokal gespeicherte Datei und nicht öffentlich erreichbar. Erst wenn der Kunde sie bewusst in einen Chatbot, ein KI-System oder eine gemeinsame Ablage einbindet, wird sie für die dort berechtigten Personen oder Systeme zugänglich. Der Kunde behält damit die Kontrolle darüber, wo die Dokumentationsdateien gespeichert werden und wer darauf zugreifen kann.

Das zweite Ergebnis ist ein strukturiertes Markdown-Dokument. Dieses enthält dieselben freigegebenen Informationen in einem klaren und textorientierten Format.

Die Markdown-Datei wird bewusst einfach und übersichtlich aufgebaut. Unnötige Formatierungen und technische Layoutinformationen werden vermieden. Dadurch ist die Datei sowohl für Menschen gut lesbar als auch für KI-Systeme effizient verarbeitbar.

Sie kann als Wissensgrundlage für einen projektbezogenen Chatbot verwendet werden.

Nutzer können dadurch Fragen zur entwickelten Lösung stellen, beispielsweise:

• Wie wird eine bestimmte Funktion verwendet?

• Welche Datenquellen werden verarbeitet?

• Wie häufig werden die Daten aktualisiert?

• Was bedeutet eine bestimmte Ausgabe oder Fehlermeldung?

• Welche Schnittstellen werden verwendet?

• Welche Voraussetzungen bestehen für den Betrieb?

• Was ist bei einer Anpassung oder Weiterentwicklung zu beachten?

Der Chatbot ersetzt die Dokumentation nicht. Er bietet einen zusätzlichen und besonders einfachen Zugang zu den darin enthaltenen Informationen. Dabei kann er Inhalte aus unterschiedlichen Abschnitten miteinander verbinden und Zusammenhänge erklären, ohne dass der Nutzer selbst das passende Kapitel suchen muss.

Für die einheitliche Erstellung der HTML- und Markdown-Dokumentation wurde ein eigenes internes Werkzeug entwickelt. Dieses führt die einzelnen Dokumentationsinhalte zusammen und erstellt daraus die beiden Übergabeformate.

Ergebnis und Mehrwert

Der Kunde erhält mit dem HTML-Dokument eine vollständige visuelle Projektdokumentation in einer einzigen Datei. Hier ein Beispiel: https://heiselanalytics.github.io/DocumentationExample

Die Dokumentation kann direkt im Browser geöffnet werden und ist nicht von einer laufenden Webseite, einem Hosting-Anbieter oder einem bestimmten Ablageort abhängig. Auch eine Internetverbindung ist für das Öffnen der Dokumentation grundsätzlich nicht erforderlich.

Dadurch kann die Datei langfristig gespeichert und jederzeit erneut verwendet werden. Sie kann ohne zusätzliche Vorbereitung an Mitarbeitende, externe Partner oder spätere Projektverantwortliche weitergegeben werden.

Der Kunde profitiert insbesondere davon, dass:

• die Dokumentation mit einem Klick im Browser geöffnet werden kann,

• keine zusätzliche Software erforderlich ist,

• alle Inhalte in einer einzigen Datei enthalten sind,

• Bilder und Tabellen nicht separat mitgeliefert werden müssen,

• keine externen Links oder Bildpfade beschädigt werden können,

• die Datei einfach versendet und geteilt werden kann,

• ein vollständiger Stand der Lösung langfristig archiviert werden kann,

• neue Personen sich schneller in das Projekt einarbeiten können,

• Betrieb und Weiterentwicklung nicht ausschließlich vom ursprünglichen Entwickler abhängen.

Die Dokumentation unterstützt sowohl die tägliche Nutzung als auch die technische Übergabe. Anwender finden Erklärungen zu Funktionen und Bedienung, während technisch verantwortliche Personen Informationen zu Datenquellen, Abläufen, Schnittstellen und Abhängigkeiten erhalten.

Mit der zusätzlichen Markdown-Datei erhält der Kunde eine kompakte und besonders gut lesbare Wissensgrundlage für einen projektbezogenen Chatbot.

Durch die klare Struktur und die reduzierte Formatierung kann das Dokument von einem KI-System effizient verarbeitet werden. Der Tokenverbrauch bleibt im Vergleich zu umfangreichen Webseiten, PDF-Dateien oder unstrukturierten Dokumentsammlungen gering.

Dies ermöglicht einen direkten und dialogorientierten Zugriff auf das vorhandene Projektwissen. Nutzer können konkrete Fragen stellen und erhalten Antworten auf Grundlage der dokumentierten Inhalte.

Der Chatbot kann dabei auch Informationen aus mehreren Abschnitten zusammenführen. Dadurch lassen sich nicht nur einzelne Fakten abfragen, sondern auch Zusammenhänge zwischen Funktionen, Datenquellen, technischen Abläufen und möglichen Einschränkungen erklären.

Der kombinierte Ansatz bietet damit zwei unterschiedliche Zugänge zu denselben Informationen:

• Das HTML-Dokument dient als vollständige und visuell aufbereitete Projektdokumentation.

• Das Markdown-Dokument dient als kompakte Wissensbasis für Chatbots, Suche und KI-gestützte Auskunftssysteme.

Die Dokumentation wird dadurch nicht nur zu einem Abschlussdokument. Sie bleibt ein aktiv nutzbarer Bestandteil der entwickelten Lösung und unterstützt deren Nutzung, Betrieb und Weiterentwicklung über die ursprüngliche Projektübergabe hinaus.

Die Dokumentation enthält außerdem einen zentralen Bereich für Support und Kontakt. Die dort dargestellten Kontaktdaten werden bei bestehender Internetverbindung aktuell abgerufen. Dadurch stehen dem Kunden auch dann die gültigen Kontaktmöglichkeiten zur Verfügung, wenn sich Telefonnummern, E-Mail-Adressen oder andere Angaben nach der ursprünglichen Projektübergabe ändern.

Kann die aktuelle Abfrage nicht durchgeführt werden, wird auf die Kontaktseite von Heisel Analytics verwiesen. Dort stehen die jeweils aktuellen allgemeinen Kontaktinformationen zur Verfügung.

Zusätzlich erhält der Kunde für sein Projekt eine gesonderte Notfallnummer. Diese ist für besonders dringende oder betriebsrelevante Fälle vorgesehen und ermöglicht eine priorisierte Kontaktaufnahme. Dadurch steht neben den regulären Supportwegen eine direkte Kontaktmöglichkeit für Situationen zur Verfügung, in denen eine zeitnahe Bearbeitung erforderlich ist.

Die Notfallnummer wird projektspezifisch und getrennt von öffentlich zugänglichen Kontaktinformationen bereitgestellt. Sie ist ausschließlich für berechtigte Ansprechpartner des jeweiligen Projekts bestimmt.

Technische Ausgestaltung

Die HTML-Dokumentation wird als eigenständige Datei bereitgestellt und kann in aktuellen Browsern geöffnet werden.

Alle benötigten Dokumentationsinhalte, Bilder und Gestaltungselemente werden direkt in die Datei eingebunden. Für die Darstellung ist keine zusätzliche Ordnerstruktur und kein öffentlich erreichbarer Dokumentationsserver erforderlich.

Die Datei kann dadurch unabhängig vom ursprünglichen Projektverzeichnis gespeichert und weitergegeben werden. Solange ein aktueller Browser verfügbar ist, kann die Dokumentation lokal geöffnet und vollständig angezeigt werden.

Die Markdown-Fassung wird als klar strukturiertes .md-Dokument bereitgestellt. Sie verzichtet auf unnötig komplexe Formatierungen und wird so aufgebaut, dass einzelne Inhalte eindeutig gegliedert, leicht aktualisierbar und effizient durch einen Chatbot verarbeitet werden können.

Beide Dokumentationsformate enthalten zentrale Projektinformationen wie:

• Projektname,

• Dokumentationsversion,

• Erstellungsdatum,

• Datum der letzten Änderung.

Dadurch kann die Dokumentation eindeutig dem jeweiligen Stand der entwickelten Lösung zugeordnet werden.

Da die Dokumentation geteilt, versendet und in einen Chatbot eingebunden werden kann, werden darin grundsätzlich keine Secrets oder sicherheitskritischen Zugangsinformationen gespeichert.

Secrets und vertrauliche Zugangsinformationen werden gesondert und über einen dafür geeigneten, gesicherten Übertragungsweg bereitgestellt.

Dadurch kann die Dokumentation innerhalb des Unternehmens weitergegeben oder in ein KI-gestütztes Wissenssystem eingebunden werden, ohne dass dabei Passwörter, Schlüssel oder andere sicherheitskritische Informationen offengelegt werden.