Projekte mit Mzeis_Documentation im Backend dokumentieren

von Matthias Zeis, aktualisiert am 03.03.2018

Magento-Projekte mit Mzeis_Documentation im Backend dokumentieren

Viele Projekte verlangen nach einer Dokumentation sowohl für den Händler als auch für den Entwickler: wie funktioniert der Bestell-Freigabe-Prozess? Welcher Cronjob wird warum wann wie ausgeführt? Was muss ich tun, um eine Landing-Page vollständig einzurichten? Was entspricht „A“ aus dem ERP-System im Webshop?

Je näher am Shop, desto besser

Es ist nicht einfach eine Dokumentation aktuell, wartbar und übersichtlich zu halten: manchmal…

gibt es gar keine fixe Stelle an der ein Projekt-Handbuch verwaltet wird, sondern ein Mail-Ordner mit wichtigen Informationen muss als Archiv vorhalten.
gibt es ein Word-Dokument / PDF, das an einer Stelle vorgehalten oder in abwechselnder Reihenfolge per Mail hin- und hergeschickt wird.
gibt es ein Wiki oder eine ähnliches Projekt, das losgelöst vom Shop gewartet wird – häufig mit extra Login, eigenem VPN zugänglich und mit ungewohnten Tools oder ungewohnter Syntax.

All diese Lösungen haben den Nachteil, dass sie die Handhabung und somit eine „lebendige“ Dokumentation erschweren. Es ist schon so eine Herausforderung, alle Änderungen zeitnah und vollständig festzuhalten. Höhere Hürden wirken sich sowohl auf das Zeitbudget als auch die Motivation negativ aus.

Aus diesem Grund habe ich mit Mzeis_Documentation eine kostenlose Extension geschrieben, die über das Webshop-Backend leicht zugänglich und erweiterbar ist und zugleich eine bekannte Oberfläche bietet.

Die Bearbeitbarkeit im Backend trägt dem Umstand Rechnung dass die Dokumentation häufig nicht nur von Entwicklern, sondern von vielen Projektbeteiligten gepflegt werden können muss: Projektmanager, Tester, die Marketingabteilung oder speziell für die Dokumentation eingeteilte Mitarbeiter müssen sich einbringen können.

Muss ich überhaupt eine Dokumentation schreiben?

Eines vorab: am besten ist eine Dokumentation, die erst gar nicht geschrieben werden muss.

Ist ein Modul oder Projekt so selbsterklärend dass es keiner Erläuterung bedarf, dann ist das für alle Beteiligten am leichtesten. In der Praxis ist das mit steigender Komplexität der Projekte jedoch nur begrenzt der Fall.

Ebenfalls sehr übersichtlich ist die Inline-Dokumentation. Lässt sich alles was zur Handhabung zu sagen ist direkt an Ort und Stelle abhandeln, dann ist für den Nutzer ebenfalls viel gewonnen. Diese Dokumentation muss aber häufig von Entwicklern über Code eingefügt werden und ist damit für andere Stakeholder nur begrenzt verfügbar.

Sollte es jedoch nötig sein eine alleinstehende Dokumentation vorzuhalten (z.B. weil die Abläufe kompliziert sind oder der Bus-Faktor erhöht werden soll) dann ist die Einbindung in den Webshop eine gute Option, um den Abstand zwischen der nutzbaren Funktionalität und ihrer Erklärung gering zu halten.

Funktionalitäten

Mzeis_Documentation unterstützt die Projekt-Dokumentation in folgender Hinsicht:

Erstellung der Dokumentation direkt im Magento-Backend
Einfaches Bearbeiten und Verknüpfen von Seiten
Umbenennen von Seiten mit Anpassung aller Referenzen
Einfache Formatierung des Textes durch den Magento-WYSIWYG-Editor
Verwendbarkeit von Variablen und Widgets
Durchsuchbarkeit der Dokumentation
Auflistung aller Seiten
Auflistung verwaister Seiten (= Seiten, auf die nicht verlinkt wird)
Deutsches und Englisches User-Interface
Autor und Zeitpunkt der Erstellung sowie der letzten Aktualisierung werden gespeichert
Rechte-Management für Anzeigen, Bearbeiten und Löschen

Die Erweiterung bildet aktuell keine Enterprise-Features wie Versionierung, granulare Rechte pro Seite oder Freigabeprozesse ab, verhilft hoffentlich aber trotzdem ein einen oder anderen Projekt zu mehr Übersicht.