Unsere Dokumentation auf dem neuesten Stand halten

Primer ist die einzige Distribution basierend auf Drupal, welche eine aktuelle Dokumentation für Editoren bietet. Darüber hinaus noch in Deutsch.

Jede Website ist anders, und die meisten Webentwicklungsunternehmen entwickeln hochgradig kundenspezifische Lösungen. Sowohl die Standardkomponenten des CMS als auch die Individualisierungen entwickeln sich schnell. Für diese Unternehmen - und für die Kunden - wird es praktisch unerschwinglich, aktuelle, auf die Redakteure ausgerichtete Dokumentationen, zu schreiben und zu pflegen.

Das Ausmass dieses Konflikts und die Herausforderungen im Pflegen der Dokumentation führen zu seltsamen Dogmen wie "Working software over comprehensive documentation" aus dem agilen Manifest. Die Dokumentation wird daher in agilen Projekten allzu oft weggelassen.

Redakteure werden so alleine gelassen und die Einarbeitung neuer Mitarbeiter ist aufwändig, was zu zusätzlichen Kosten aufgrund vieler Supportanfragen und der Schulungen führt.

Ziel dieses Projektes war es, den Prozess der Pflege der Primer-Dokumentation zu vereinfachen und zu automatisieren, um Kunden aktuelle und hilfreiche Dokumentationen zur Verfügung zu stellen und so den Prozess der Website-Bearbeitung zu erleichtern und die Kosten im Zusammenhang mit dem Support zu reduzieren.

Die Struktur der Software-Benutzeroberfläche und der Dokumentation ist so gestaltet, dass sie auch für alle Projekte mit unterschiedlichen Anpassungsgraden anwendbar ist.

Zusätzlich belegen aktuelle Dokumentationen die Einfachheit der Lösung häufiger Anforderungen für potentielle Neukunden während der Angebotsphase.

Wir haben ein Tool entwickelt, mit dem wir automatisch Screenshots der Dokumentation erstellen und aktualisieren können. Auf diese Weise können wir die Benutzererfahrung unseres Produkts kontinuierlich verbessern, ohne den Vorteil aktueller Dokumentations-Screenshots zu verlieren.

Das automatische Erstellen von Screenshots hat auch noch andere Vorteile:

• Mehrsprachige Dokumentations-Screenshots können mit nur einer Variablenänderung durchgeführt werden.
• Benutzerrolle und Berechtigungen in einem Screenshot können zur Steuerung sichtbarer Elemente leicht angepasst werden
• Entwickler können teilnehmen. Da die Screenshots durch Skripte und nicht manuell erstellt werden, können die Entwickler leicht Skripte schreiben, um die von ihnen entwickelten Prozesse zu dokumentieren.
• Als netter Nebeneffekt lassen sich Regressionen in der Admin-Benutzeroberfläche leicht erkennen.

Bisher haben wir mehr als 500 Screenshots erzeugt, die in mehreren Iterationen neu generiert wurden und nicht weiter bearbeitet werden müssen, und wir können es uns jetzt leisten, die weniger genutzten Funktionen zu dokumentieren.

Zusätzlich ist es möglich, in jeden Screenshot hineinzuzoomen und auf den Screenshot des gesamten Bildschirms zuzugreifen, um sich zu orientieren.

Diese Methode hängt von 2 Schritten ab: Generierung der Screenshots und deren Aktualisierung auf der Website.

Der erste Schritt - die automatische Generierung der Screenshots - wird mit Hilfe des Test-Frameworks Behat durchgeführt. Wir verwenden Behat bereits für unsere automatisierten Tests verwendet, um zu überprüfen, ob sich die Website wie erwartet verhält. Es stellt sich heraus, dass Behat aber auch zur Generierung von Screenshots für die Dokumentation hervorragend geeignet ist.

In unserem Fall arbeiten wir mit diesem Rahmen, um aussagekräftige Screenshots zu erstellen. Wir verwenden es auch zum Hinzufügen von css-Elementen wie Hervorhebungen, Zahlen usw.  

Auf diese Weise werden kosmetische und kontextuelle Änderungen der dokumentierten Seiten automatisch berücksichtigt und die Hervorhebungen sind immer an der richtigen Stelle.

Der zweite Schritt dieses Prozesses besteht darin, die Screenshots nahtlos, aber nicht blind zu aktualisieren. In der Tat wollen wir nicht jeden einzelnen neuen Screenshot überprüfen müssen, insbesondere wenn sie völlig identisch sind, aber wir wollen auch keine unerwünschten Änderungen verpassen.

Wir haben zunächst einen bestimmten Medientyp erstellt. Dieser Medientyp enthält den aktuellen Screenshot mit allem, was damit verbunden ist, wie die unbeschnittene Version des Screenshots und alle anderen wichtigen Informationen (Sprache, gewünschter Benutzerstatus usw.). Er kann auch eine zweite, aktualisierte Version des Screenshots enthalten.

Ein automatisiertes Skript wird verwendet, um dieses zweite Feld mit dem neuen Screenshot zu füllen, wenn es sich von dem aktuellen unterscheidet. Somit sind nur tatsächlich geänderte Screenshots "zu prüfen".

Wenn sich der Screenshot ändert, können wir ihn überprüfen und entscheiden, ob der frühere Screenshot ersetzt werden soll oder nicht. Ein netter Nebeneffekt ist, dass wir auch sehr leicht unerwünschtes Verhalten in unserer Plattform erkennen und schnell korrigieren können.

Wir können dann einfach die Änderung auf dem Überprüfungsbildschirm bestätigen und die Screenshots auf der Website werden automatisch aktualisiert.

Primer ist basierend auf Komponenten aufgebaut, die allen Projekten gemeinsam sind. Alle Kunden nutzen dieselbe Backend-Plattform, was uns ermöglicht, nützliche Dokumentation zu entwickeln und zu pflegen. 

Dies wiederum macht unsere Lösung zur einzigen Drupal-Distribution, die eine solche Dokumentation anbietet.