Einführung eines Dokumentations-Frameworks

Hallo zusammen,

um die Dokumentation des Masterportals zu verbessern möchte ich den Einsatz eines Dokumentations-Frameworks vorschlagen. Die momentane Umsetzung kann an vielen Stellen verbessert werden:

Siehe #752
Viele Dateien werden überhaupt nicht auf der Webseite angezeigt und sind damit effektiv für Nutzer die sich dieses Umstandes nicht bewusst sind nicht existent.
- Neue Dateien müssen manuell eingebunden und verlinkt werden, eine übergeordnete Navigation existiert nicht.
Keine Suchfunktion
Inhaltsverzeichnis steht nur oben auf der Seite zur Verfügung, was auf großen Seiten (z.B. config.json) schnell zur Desorientierung führt.

Diese Probleme können recht einfach gelöst werden, da die Dokumentation bereits in Markdown vorliegt. Für dieses Format gibt es exzellente Website-Generatoren, die mit wenig Aufwand schöne und praktische Dokumentation erstellen. Mein Favorit ist dabei mkdocs mit dem Material Theme welches ich bereits seit über zwei Jahren in meinem privaten Open-Source Projekt verwende:

Material for MkDocs wird seit 2016 vom Kölner Martin Donath unter der MIT-Lizenz entwickelt. Das Projekt hat ein Sponsorware-Finanzierungsmodell, welches folgendermaßen funktioniert: Große neue Features (zuletzt z.B. eine Blog-Funktion) werden nur für zahlende Kunden verfügbar gemacht. Wird ein bestimmtes Finanzierungsziel überschritten wird das Feature in das öffentliche Repository gemerged wo es unter MIT jedem zur Verfügung steht. Dieses Modell ist sehr erfolgreich (momentan werden etwa 157.000$ im Jahr aufgebracht). Daher ist die Pflege des Produktes gesichert.

Die oben verlinkte Webseite von mkdocs-material ist selbst bereits mit der Anwendung erstellt und fungiert daher als gutes Beispiel für Aussehen und Funktionen.

Nötige Schritte

Schaffung einer sinnvollen Dokumentations-Struktur in der alle Dateien enthalten sind.
Aufsetzen des mkdocs Projektes
Migration der bestehenden Dateien zu mkdocs:
- Erstellen der festgelegten Struktur
- Löschen der Zurückverlinkungen, Inhaltsverzeichnisse etc, da diese automatisch generiert werden.
- Geringfügige Syntaxanpassungen
Review durch die Community und ggf. iterative Anpassungen

Möglicherweise ist auch die Einrichtung einer Build-Pipeline für ein automatisches Deployment auf docs.masterportal.org sinnvoll. Das hängt von den bestehenden Prozessen und Infrastrukturen ab, die mir unbekannt sind.

Herausforderungen

Ich habe bereits einen POC erstellt, dabei sind mir einige Dinge aufgefallen, die beachtet oder diskutiert werden sollten:

Möglicherweise Anpassung des mpconfigparsers notwendig, enge Kopplung mit nächstem Punkt:
Auf einigen Seiten werden technische Pfade (z.B.Portalconfig.menu.tools) als Überschriften verwendet. Diese sind teilweise extrem lang und passen optisch in kein Inhaltsverzeichnis (TOC) am rechten Seitenrand. Hier gibt es mehrere Möglichkeiten:
- Auf solchen Seiten wie bisher kein TOC rechts der Doku, nur oben auf der Seite.
- Im TOC nur den jeweiligen Namen der JSON-Section (geschachtelt, so dass sich eine Struktur ergibt). Hier würde sich auch die Frage stellen ob der Name Case-Sensitive ist. Ich finde mit großem Anfangsbuchstaben sieht der TOC besser aus.
- Gleiche Option wie vorher, nur in der Überschrift selbst ist der volle Pfad sichtbar. Das würde syntaxtechnisch folgendermaßen definiert: Portalconfig.searchbar.hitmap { data-toc-label='Hitmap' }`
- Pfad anstatt mit Punkten mit z.B. /trennen, dann bricht mkdocs den Namen um.
- Pfad mit Punkten schreiben und im TOC umbrechen wenn zu lang (erfordert customizing von mkdocs).
Wie soll die Dokumentationsstruktur aussehen?
- Mein Vorschlag wäre drei Reiter, darunter jeweils die Seiten:
  - Tutorials mit Quick Start etc.
  - User Docs mit der Doku für Endnutzer
  - Developer Docs mit allen Inhalten für Entwickler
Wie soll mit zweisprachigen Dokumentationsseiten umgegangen werden? Mindestens config.json.de.md ist ein Dublikat. Sollen diese weiterhin geflegt werden? Soll eine parallele Dokumentation auf Deutsch aufgebaut werden? Dies wäre per Language Switcher technisch gut machbar, bedeutet allerdings massiven zusätzlichen Pflegeaufwand und praktisch garantiere Inkonsistenzen.

Ich würde mich für die Umsetzung zur Verfügung stellen, wenn dieser Change angenommen werden würde. Hilfe aus der Community wird aber auch gerne angenommen :)

MVP live auf: https://saltyaimbotter.github.io/masterportal/User/About/ Achtung! Viele Links sind noch kapput.

Vielleicht kann das Thema ja auch in der nächsten Sitzung des technischen Komitees besprochen werden, ich hatte es in der letzten Sitzung schon mal angeteasert.

Viele Grüße aus Köln

Lars Baum

Nötige Schritte

Herausforderungen

Comments (5)