Anton Dollmaier

Anton Dollmaier


Relaunch der ADITSYSTEMS Dokumentation

05 Oct 2019 »

Seit Anfang Oktober 2019 ist die Kunden-Dokumentation der ADITSYSTEMS nun an einer zentralen Stelle abrufbar:

Bisher haben wir dafür ein Dokuwiki eingesetzt, welches über einen XML-RPC-Wrapper unter https://kunden.aditsystems.de/wiki abrufbar war.

Die technischen Neuerungen der Doku:

  • basierend auf Jekyll, Theme mit UIKit.
  • somit vollständig in Markdown geschrieben.
  • für den internen Review-Prozess sowie die Deployments nutzen wir unsere eigene Gitlab-Installation.
  • jeder Commit wird mittels HTML-Proofer validiert: gibt es fehlerhafte Verlinkungen, fehlende Bilder oder ähnliche Fehler, so wird verhindert, dass dieser Commit die Produktiv-Umgebung erreicht.
  • die Konfiguration des Webservers ist ebenfalls vollautomatisiert:

Durch diese Automatisierung kann die Dokumentation nun von jedem mit passenden Zugriffsrechten ergänzt werden.

Da die gesamte Dokumentation in Markdown geschrieben ist und in einem Git-Repository liegt, kann die Dokumentation auch offline gelesen werden.

Leider dauert ein Build aktuell noch ca. 3-5 Minuten, was unter anderem an der langen Build-Zeit der Navigation liegt. Die “üblichen” Methoden, die Build-Zeiten von Jekyll zu verbessern, waren nur bedingt erfolgreich - hier ist noch Optimierungs-Potential.

Nach diesem ersten Schritt ist jetzt unsere interne Dokumentation an der Reihe. Mal schauen, was sich dabei dann berichten lässt.

© Anton Dollmaier