Werkzeuge zur Erstellung einer Drupal-Website-Dokumentation

Ob Freelancer oder Vertragsprogrammierer, wir stehen alle vor dem gleichen Problem, wenn wir mit einem bestehenden Projekt für einen Kunden beginnen: Wie können wir uns schnell und (wenn möglich) schmerzlos mit der bestehenden Struktur und dem Code vertraut machen? Wahrscheinlich hat jeder von uns mindestens einmal in seiner Karriere hoffnungsvoll gefragt: Haben wir hier irgendeine Dokumentation?

Wenn Sie es nicht einfach erklären können, verstehen Sie es nicht gut genug. (Albert Einstein)

Bedeutung der Projektdokumentation

Dokumentation ist Teil des Produkts, eine unschätzbare Ergänzung und ein Leitfaden – für den Programmierer, den Manager, den Product Owner und den Endbenutzer. Eine gut strukturierte und gut geschriebene Dokumentation ist eine Win-win-Situation. Auf der einen Seite minimieren Sie den Umfang der Fragen, die der Kunde Ihnen stellen wird, und auf der anderen Seite erleichtern Sie es den Personen, die Ihrem Team beitreten oder die Systemunterstützung nach Ihnen übernehmen werden. Daher ist das Vorhandensein und (was besonders wichtig ist) das Pflegen der aktuellsten Dokumentation eine Investition und eine strategische Entscheidung, insbesondere in großen Projekten.

Wenn es nicht dokumentiert ist, existiert es nicht. (Sitepoint, A Guide to Writing Your First Software Documentation)

Arten der Projektdokumentation

Auf der höchsten Ebene der Verallgemeinerung können wir die Projektdokumentation in die Systemdokumentation und die Endbenutzerdokumentation unterteilen.

Der erste Typ von Materialien wird besonders für Entwickler interessant sein, der zweite – meist für den Kunden und den Endbenutzer (den Internetnutzer). Doch wie kann man alle Feinheiten und Besonderheiten eines bestimmten Projekts erklären, wie dokumentiert man am besten die Prozesse, die im Backend ablaufen, und wie zerstreut man die Zweifel der Benutzer auf visuelle und einfache Weise? Zur Rettung kommt eine ganze Reihe von Werkzeugen, deren Funktionen Ihnen helfen, diese Fragen zu beantworten und auch Ihre Website-Dokumentation zu erstellen.

Buchähnliche Dokumentation

Eine der häufig verwendeten Formen der Dokumentationssammlung ist das Erstellen von hierarchischen Inhalten mit Kapiteln und Unterabschnitten – genau wie in einem Buch, d.h., einer Papierform der Benutzeranleitungen, die zu jedem Produkt gehört.

Es gibt verschiedene Werkzeuge zur Erstellung einer solchen Inhaltsstruktur. Sie alle verfügen über integrierte Texteditoren, die es Ihnen ermöglichen, problemlos Codefragmente, Listen, Tabellen und Medienanhänge hinzuzufügen.

Confluence

Confluence ist eines der Atlassian-Unternehmens erfreulichsten und leistungsstärksten Werkzeuge. Die Entwickler selbst beschreiben es als einen freundlichen Ort, an dem Wissen und Zusammenarbeit aufeinandertreffen. Die tägliche Arbeit mit diesem Werkzeug beweist, dass dies wahr ist. Wir sind bereits an die Struktur von Wikiseiten gewöhnt, sodass auch nicht-technische Personen in Confluence navigieren und Inhalte hinzufügen können.

Nach ein paar einfachen Schritten (insbesondere, wenn Sie bereits andere Atlassian-Produkte verwenden) erhalten Sie eine personalisierte Website mit der Möglichkeit, mehrere Bereiche (z. B. für mehrere Produktversionen) zu erstellen, innerhalb derer Seiten mit Artikeln erstellt werden können. Ihnen steht ein umfangreiches Tutorial und mehrere Dutzend Inhaltsvorlagen zur Verfügung. Die Erstellung Ihres "Buchs" wird erleichtert durch die Möglichkeit, frei zu ziehen und über die Reihenfolge und den Ort der hinzugefügten Unterseiten zu entscheiden sowie die Möglichkeit, Tags zu vergeben, zu liken, zu kommentieren und sie zu markieren. Das Tool ist visuell klar und lesbar. Darüber hinaus bietet die kostenlose Version 2 GB Platz, und Sie können bis zu zehn Personen zur Zusammenarbeit einladen. Confluence ist einen Versuch wert, insbesondere wenn Sie Ihren Code im Bitbucket-Repository aufbewahren und Aufgaben mit Jira Software verteilen.

GitHub Pages und GitLab Wiki

Wenn Sie Ihre Dokumentation gerne in der Nähe Ihres Codes aufbewahren möchten, sind die von Hosting-Websites angebotenen Wiki-Funktionen, die speziell für diesen Zweck erstellt wurden, die ideale Lösung. Sicher, hier stehen Ihnen keine Artikelvorlagen zur Verfügung, aber die eingegebenen Inhalte sind immer zur Hand – direkt neben dem Repository, den Aufgaben oder den neuen Codeimplementierungsprozessen. Die Inhaltsorganisation ähnelt der zuvor erwähnten Confluence. Gitlab ermöglicht sogar den Import der bestehenden Dokumentation aus diesem Tool. Einzelne Artikel können durch Angabe des Pfads im Verzeichnisbaum Ihrer Kapitel gruppiert werden. Beim Hinzufügen von Inhalten steht Ihnen ein einfacher Editor zur Verfügung, der Formate wie Markdown, Rdoc, AsciiDoc, reStructuredText oder Org unterstützt, und der Veröffentlichungsprozess selbst wird durch Hinzufügen eines weiteren Codepakets (Commit-Nachricht) durchgeführt. Github Pages bietet auch standardmäßige Skins, die Ihre Dokumentationsseite professionell aussehen lassen.

Camunda Modeler und Process Street

Wenn das Workflows-Modul das Zentrum ist, um welches sich die Funktionsweise der gesamten Website dreht, dann werden zur Erklärung aller Abhängigkeiten und Prozesse, die auf der Website ablaufen (z. B. wie der Prozess der Kreditaufnahme, der Antragsstellung auf Förderung, der Terminbuchung usw. durchgeführt wird), solche Werkzeuge wie Camunda Modeler oder Process Street sich als unschätzbare Hilfe erweisen. Sie sind sowohl bei der Planung als auch bei der Dokumentation der Prozesse nützlich. Der Hauptzweck dieser Tools ist die Unterstützung des Geschäftsprozessmanagements (BPM) und (im Fall von Camunda) das Erstellen von Entscheidungsmodellen und Notationsbäumen (DMN).

Kurz gesagt, wenn es auf Ihrer Website wiederkehrende Prozesse gibt, die es wert sind, dokumentiert zu werden, können Sie dies mit diesen Tools tun. Sie können Dokumente erstellen, die Verfahren enthalten oder Prozesse für Ihre Kollegen in wenigen Sekunden starten. Process Street wird verwendet, wenn neue Lösungen implementiert oder neue Systemversionen veröffentlicht werden.

Während das Management von den Möglichkeiten von Process Street begeistert sein wird, werden Entwickler und Business-Analysten eher den Camunda Modeler verwenden. Das Programm funktioniert mit allen Betriebssystemen und funktioniert als Cloud. Es ermöglicht Ihnen, alle Prozesse und Verbindungen zwischen den Servern genau abzubilden. Es gibt auch einen vorgesehenen Platz, um alle notwendigen Informationen zu sammeln, die ein Entwickler benötigen könnte: Serveradressen, das Format der gesendeten Anfragen und der empfangenen Antworten, zusammen mit Parametern usw. Das Ganze ist sehr übersichtlich und intuitiv.

Codeähnliche Dokumentation

Es ist Zeit, zu den Lösungen überzugehen, die die Herzen der eingefleischtesten Programmierer erwärmen – Dokumentation im Code! Aus der Perspektive eines neuen Teammitglieds in einem großen Projekt für einen Kunden ist Dokumentation als Teil des Codes die perfekte Lösung. Die Kultur der technischen Dokumentation, wie wir sie heute verstehen, wurde 2014 von den Twitter-Mitarbeitern gestartet, die einen Schritt weiter gingen als das allgemein akzeptierte Muster – ein Entwickler schreibt den Code, lasst sie auch die Dokumentation schreiben – und sagten, dass sie die Dokumentation wie den Code schreiben sollten. Der Dokumentation-wie-Code-Ansatz übertraf alle Erwartungen. Wir sprechen hier davon, die Dokumentation an derselben Stelle wie den Code zu schreiben – mit genau demselben Veröffentlichungsprozess wie beim Hinzufügen des Codes: Commit, Pull Request, Build. Kommentare im Code begünstigten diesen Ansatz bereits zuvor.

ReadMe.md!

Sicherlich ist jeder auf eine Datei namens README.md gestoßen. Vielleicht war sie als einfacher Text oder in einem der sogenannten leichten Textformate geschrieben. Sie enthält grundlegende Informationen zum Projekt, wie man dessen Entwicklungsversion lokal einrichtet, wer es erstellt und pflegt usw.

Sie können jedoch einen Schritt weiter gehen und die gesamte Projektdokumentation auf diese Weise erstellen. Um dies zu tun, ist es jedoch ratsam, eines der verfügbaren Formate zu verwenden, das die vereinfachte Version des Textes in formatierten Text umwandelt, den der Benutzer leicht lesen kann. Zu den am häufigsten verwendeten Formaten gehören Markdown und reStructuredText.

Erstellen Sie Ihre Dokumentation

Was wäre, wenn Sie den gesamten Prozess automatisieren könnten, basierend auf den Kommentaren in dem vorhandenen Code, und gleichzeitig – eine Art Dokumentationsbuch erstellen könnten, das sich mit jeder Änderung im Code selbst aktualisiert? Natürlich kann nichts die menschliche Beteiligung an der Erstellung der Projektdokumentation ersetzen, aber die Möglichkeit, deren Rahmen, ihr Hauptaußenbild automatisch zu erhalten, klingt ermutigend.

Es gibt viele solcher Generatoren, und von diesen sind die für Drupal-Benutzer am nützlichsten natürlich diejenigen, die auf dem PHP-Code basieren. Empfehlenswert sind hier:

• ApiGen – erstellt saubere API-Dokumentation auf Basis des PHP-Quellcodes.
• Dexy – einer der vielseitigsten Generatoren, unterstützt mehrere Programmiersprachen, sowie Eingabe- und Ausgabeformate.
• docgenerator – ermöglicht es, die Dokumentation in Form von Markdown-Dateien zu organisieren.
• DocumentUp – für GitHub-Codeinhaber ermöglicht es, die Dokumentation, die mit dem Markdown-Format erstellt wurde, zu verbessern.
• Doxygen – unterstützt viele Programmiersprachen, generiert die Dokumentation online (HTML) oder als Handbuch in LaTeX oder anderen Textformaten (PDF, MS Word).
• phpDocumentor – eines der ersten seiner Art, ermöglicht das Erstellen von Klassendiagrammen in UML, unterstützt die neueste PHP-Version, bietet eine breite Palette an Hilfen und hat viele Jahre Erfahrung.
• PhpDox ist nicht auf API-Dokumentation beschränkt. Die gesammelten Informationen werden in den XML-Dateien gespeichert, die frei modifiziert und dann als HTML-Dateien generiert werden können.

Verwenden Sie Drupal für die Projektdokumentation

In unserer Drupal-Agentur haben wir entschieden, Drupal zur Erstellung der Dokumentation für den internen Gebrauch des Unternehmens zu verwenden. Die Grundversion einer Drupal-Website ist einfach einzurichten und kommt mit Standard-Inhaltstypen, die ausreichen, um loszulegen. Wir müssen nicht einmal etwas Neues lernen – wir sind schließlich Drupal-Spezialisten! In unserem Fall haben wir auch das „Book“-Modul aktiviert. Die hinzugefügten Seiten erstellen Sammlungen, die miteinander verknüpft sind – genau wie bei einem echten Buch.

Die Hauptansicht der Dokumentation besteht aus zwei Teilen: Auf der linken Seite befindet sich ein Block mit dem Inhaltsbaum, auf der rechten Seite wird der Inhalt des ausgewählten Kapitels geladen. Jede Seite wird als eigener Knoten hinzugefügt, wir verwenden den Standard- CKEditor zur Erstellung/Bearbeitung der Inhalte. Er wird mit einem zusätzlichen CodeSnippet-Plugin erweitert. Wir haben alles in unseren Unternehmensfarben angepasst, und... voilà! Die Inhalte werden sowohl von Entwicklern als auch von nicht-technischen Personen moderiert. Es speichert Inhalte, die von typischen HR-bezogenen Themen bis hin zur lokalen Projektentwicklung reichen. Unsere neuen Mitarbeiter erhalten ein fertiges Wissensrepository darüber, wie sie alle Unternehmensfragen navigieren und wie sie die Arbeit an dem zugewiesenen Projekt beginnen können.

Zusammenfassung

Es gibt viele Werkzeuge, die Ihnen helfen, aktuelle Dokumentationen zu erstellen und vor allem zu pflegen. Welche davon zu wählen sind, hängt von den Besonderheiten Ihres Projekts ab – seiner Größe, der Anzahl und dem Typ der verwendeten Module. Auch beeinflusst, ob die Website überwiegend statisch oder prozessbasiert ist, wer die Dokumentation erstellen und verwenden wird, ob Sie sie freigeben möchten und viele, viele weitere Faktoren. Tatsache bleibt jedoch, dass die Dokumentation Teil des Produkts ist und einen wirtschaftlichen Wert hat – da sie es ermöglicht, die Kosten zu reduzieren (d.h., die Stunden des Entwicklers, um sich mit allem vertraut zu machen) – bleibt bestehen. Gute Dokumentation hilft auch dabei, Kunden zu gewinnen (wie wir bereits zitiert haben – „wenn es nicht dokumentiert ist, existiert es nicht“ ;)) Also los!