Darum geht‘s
- Warum wir einen neuen, effizienteren Tech-Stack brauchen
- Wie die neue Architektur hinter unserer Dokumentation aussieht
- Welche konkreten Verbesserungen bei Performance, Suche und Nutzererlebnis spürbar sind
- Welche Vorteile sich für unser Entwicklerteam und für Sie als Zammad-Nutzer ergeben
Die Zammad-Dokumentation hat ein umfassendes Upgrade erhalten! Nicht nur optisch, sondern auch strukturell haben wir sie komplett überarbeitet, um Ihnen die Arbeit mit Zammad zu erleichtern – egal, ob Sie Entwickler, Admin oder Nutzer sind.
Warum wir die Dokumentation neu aufgebaut haben
Die Zammad-Dokumentation ist seit jeher ein zentraler Bestandteil unserer Open-Source-Philosophie. Sie ist klar strukturiert, öffentlich zugänglich und unterstützt Teams dabei, Zammad effektiver zu nutzen – Tag für Tag.
Lange Zeit basierte unsere Dokumentation auf Sphinx, einem Python-basierten Static Site Generator, der mithilfe von reStructuredText Inhalte für verschiedene Ausgabemedien erzeugt. Gehostet wurde sie über Read the Docs Community – eine fantastische und kostenlose Plattform, die uns über Jahre hinweg gute Dienste geleistet hat.
Doch mit der Zeit nahm die Beliebtheit dieses alten, Python-basierten Stacks ab, während seine Komplexität wuchs und mit ihr das gefürchtete "Dependency Hell". Gleichzeitig entstanden modernere, benutzerfreundlichere Alternativen, die es wert waren, genauer betrachtet zu werden.
Das Comeback des Static Web
In den letzten zehn Jahren hat das statische Web ein beeindruckendes Revival erlebt. Mit dem Ziel, selten aktualisierte Inhalte effizient an eine wachsende Zahl von Nutzern auszuliefern, sind zahlreiche Static Site Generatoren auf den Markt gekommen und wurden dank niedriger Hosting-Kosten und blitzschneller Ladezeiten begeistert aufgenommen.
In einer zunehmend dynamischen digitalen Welt hat sich dabei eine natürliche Balance entwickelt: Statische Websites erwiesen sich als perfekte Lösung für Anwendungsfälle wie Software-Handbücher und Dokumentationen. Und ganz nebenbei machten sie auch einfach mehr Spaß – dank neuer, schlanker Markup-Sprachen wie Markdown, die unsere Arbeitsweise erleichterten und für mehr Übersicht sorgten.
Ein moderner Tech-Stack mit Vue.js und Vite
Für unser großes Desktop Rewrite-Projekt haben wir uns für einen modernen Tech-Stack entschieden: Das Vue.js-Framework bildet die Basis, während Vite als schnelles und effizientes Bundling-Tool dient. Da lag es nahe, auch für unsere Dokumentation nach einer Lösung innerhalb dieses Ökosystems zu suchen – schließlich wollten wir die vorhandene Expertise unseres Teams optimal nutzen.
Unsere Wahl fiel auf VitePress – eine Plattform, die genau das versprach, was wir suchten. Also haben wir sie ausprobiert. VitePress baut auf dem bewährten VuePress auf, bietet native Markdown-Unterstützung und profitiert von einer starken Community. Besonders gefallen hat uns das schlanke Standard-Theme, das sowohl einen hellen als auch einen dunklen Modus mitbringt – ein echtes Plus für eine angenehme Lesbarkeit, egal ob bei Tageslicht oder in dunklen Umgebungen.
Intelligente Navigation dank Flat-File-Struktur
Die Struktur einer statischen Website ist ihr Rückgrat – sie sorgt dafür, dass Seiten logisch organisiert sind und Informationen schnell auffindbar sind. Flat-File-Systeme sind dafür wie geschaffen: Einfach die Datei in den gewünschten Ordner legen und fertig. Während VitePress diese Funktion nicht standardmäßig mitbringt, lässt sie sich dank eines Community-Plugins problemlos hinzufügen.
Ein großer Vorteil: Die Hauptnavigation kann automatisch aus der Ordnerstruktur abgeleitet werden. Das sorgt nicht nur für eine saubere Organisation, sondern auch für ein klares URL-Schema ohne unnötige Verschachtelungen.
Die sekundäre Navigation funktioniert nativ und basiert direkt auf den Überschriften innerhalb der Markdown-Dateien. Adieu, manuelle Inhaltsverzeichnisse! Was früher mühsam per Direktive erstellt werden musste, funktioniert jetzt einfach out of the box.
Und dann gibt es noch das Frontmatter: VitePress unterstützt den quasi-Standard für Markdown-Metadaten. Mit nur ein paar speziellen Schlüsseln lassen sich nicht nur das Erscheinungsbild einer Seite, sondern auch ihre Position in der Navigation flexibel steuern. Das eröffnet spannende Möglichkeiten für zukünftige Erweiterungen und ist ein echter Gewinn für die Benutzerfreundlichkeit.
Mehrsprachigkeit – endlich praktikabel gelöst
Die Internationalisierung unserer Dokumentation war anfangs eine echte Herausforderung. Zwar bietet VitePress native Unterstützung für mehrsprachige Inhalte, doch die Umsetzung ist – gelinde gesagt – etwas umständlich. Alle übersetzten Markdown-Dateien müssen von Anfang an in der richtigen Struktur vorliegen, was sich nur schwer mit unserer Weblate-basierten, communitygetriebenen Übersetzungsplattform vereinbaren ließ.
Die Lösung kam in Form eines kleinen, aber mächtigen Perl-Tools namens po4a. Damit konnten wir weiterhin auf gettext-Format als Basis setzen, hatten aber zugleich einen zuverlässigen Pre-Build-Prozess, der uns alle benötigten Dateien automatisch vorbereitete.
Das Ergebnis: Unser ursprünglicher Wunsch wurde erfüllt: Nur die englischen Originalinhalte müssen bearbeitet werden, während die restlichen Sprachen vor dem Build automatisch übersetzt und generiert werden. Ein kleiner Wermutstropfen bleibt: Einige Markdown-Elemente schleichen sich gelegentlich in die Übersetzungsdateien ein. Doch diesen Kompromiss konnten wir guten Gewissens eingehen, denn der neue Prozess spart uns enorm viel Aufwand und macht die Mehrsprachigkeit unserer Doku endlich praktikabel.
Für Sie als Nutzer bedeutet das eine konsistentere Übersetzungsqualität, mehr verfügbare Sprachen und eine Dokumentation, die weltweit zugänglich ist.
Automatische Screenshots: Immer aktuell, immer konsistent
Die Dokumentation von Zammad war schon immer reich an visuellen Elementen – neben Textanleitungen setzten wir auf Animationen und Screenshots, um jeden Schritt anschaulich zu erklären. Doch die Pflege dieser Bilder war mühsam: Selbst kleinste UI-Änderungen führten dazu, dass zahlreiche Screenshots in den Anleitungen aktualisiert werden mussten.
Also kam die Idee auf, diesen Prozess zu automatisieren. Da die Zammad-App bereits als Docker Compose-Stack läuft, können wir sie jederzeit lokal mit der neuesten Version starten. Und weil sich ein solches System auch deterministisch mit Beispieldaten befüllen lässt, fehlte nur noch ein Tool, das die benötigten Screenshots automatisch erstellt.
Hier kam Cypress ins Spiel. Eigentlich für automatisierte Tests gedacht, bietet die Plattform ein leistungsstarkes, skriptfähiges System für Screenshots auf Abruf. Mit ein paar Zammad-spezifischen Erweiterungen haben wir ein Setup entwickelt, das einfach ein geeignetes End-to-End-Testskript ausführt – und schon werden alle benötigten Bilder generiert.
Der Clou: Das Ganze funktioniert beliebig oft, ohne manuelles Zutun. Kein Nachpflegen einzelner Screenshots mehr, keine binären Dateien im Repository und die Nutzer sehen immer genau, wie die aktuelle Zammad-Version aussieht.
CI/CD-Pipeline: Der letzte Baustein für eine automatisierte Dokumentation
Um unser neues Dokumentationssystem abzurunden, haben wir eine CI/CD-Pipeline implementiert. Dieser automatisierte Prozess übernimmt mehrere essenzielle Aufgaben und sorgt dafür, dass unsere Dokumentation stets aktuell bleibt:
- Klonen des Dokumentations-Repositorys
- Einbinden der neuesten Übersetzungen aus Weblate
- Erstellen aktueller Screenshots
- Generieren der statischen Dokumentations-Website
Für das Deployment haben wir festgestellt, dass das Hosten auf unserem eigenen Server langfristig mehr Kontrolle bietet. Dennoch lässt sich dies flexibel anpassen, je nach Bedarf. Glücklicherweise gibt es heute viele kostenlose Hosting-Plattformen wie GitHub Pages, GitLab Pages oder Cloudflare Pages, die eine einfache Veröffentlichung ermöglichen.
Zammad-Dokumentation 2.0 – Was meinen Sie?
Die neue Zammad-Dokumentation ist für Sie gemacht – und wir möchten sie gemeinsam mit Ihnen weiter verbessern. Deshalb laden wir Sie herzlich ein, die neue Dokumentation auszuprobieren und sich selbst ein Bild zu machen. Wenn Sie Fehler entdecken, Ideen haben oder Inhalte beitragen möchten, freuen wir uns über Ihre Mitwirkung.
Sie können ganz einfach ein Issue in unserem GitHub-Repository eröffnen, einen (oder mehrere) Pull Requests einreichen, oder sich an der Übersetzung auf Weblate beteiligen. Die Community wird es Ihnen danken!