Relaunch der ADITSYSTEMS Dokumentation
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:
- Nginx mit HTTP/2 usw.
- SSL-Zertifikat von Let’s Encrypt, abgerufen mittels dehydrated
- Puppet-Module zur Automatisierung, unter anderem bzed-dehydrated
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.