In der Firma haben wir ein MediaWiki und so begeistert ich anfangs auch war – was MediaWiki angeht – ich kann es nicht mehr leiden. Es ist beschissen zu pflegen; die Debian Version ist meistens hoffnungslos veraltet und die Plugins sind in der Regel auch … ach lassen wir das.

Egal.

Jeder weiß, wenn ein Wiki als Dokumentationsquelle dienen soll, benötigt es einiges an Disziplin. Die Struktur darf nicht wie Kraut und Rüben wachsen und die Seiten müssen auch (thematisch) gefunden werden können. Die Sache mit der Pflege der Inhalte ist ohnehin ein Thema für sich. Seit langem setzen wir in der Firma GitLab ein, was die Repo Funktion von Redmine ersetzt hat (was eh nur als Frontend dient(e)). GitLab erledigt einfach viele Dinge schöner und bietet auch ein Wiki an, welches auf MarkDown basiert. Allerdings hat es den unschönen “Nachteil”, dass es projektbezogen ist. Das ist oftmals nicht sehr praktisch, wenn die Dokumentation eher übergreifend sein soll.
Ein weiterer Nachteil ist, dass es relativ umständlich erreichbar ist (klick / klick …). Wer als Mitarbeiter nicht drauf hingewiesen wird, sucht an der falschen Stelle, da Markdown auch im regulärem Repo interpretiert wird. Schön ist allerdings, wenn man wirklich das Wiki dort verwendet, ist es ein eigenes (!) Repository, welches per git clone erreichbar ist. Ich machte mich also an die Arbeit, die Mediawiki Seiten nach MarkDown zu konvertieren. Es war eine Drecksarbeit. Die Ursache waren vielfältig. Zum einen haben die wenigsten Kollegen die Wikisyntax beachtet, zum anderen war das Tool um aus dem XML Export Markdown zu erstellen, hoffnungslos überfordert. Auch nicht viel besser war der Umweg über den Import nach DokuWiki(!) und dann via Pandoc nach Markdown. Kleiner Tipp daher: wenn ihr nicht gerade hunderte von Seiten habt, kopiert den Inhalt lieber von Hand und korrigiert/ersetzt die Syntax. Dauert zwar länger, hat aber vier entscheidende Vorteile:

  • Seiten entstauben, bei denen die Inhalte nicht mehr stimmen
  • Obsolete Seiten gleich löschen
  • Eine Struktur reinbringen
  • Syntax fixen

Nachdem ich also ausgiebig geflucht und konvertiert hatte, stach mir bei irgendeiner Google Suche GitLab “Pages” ins Auge. Im Grunde ist es nichts anderes, als dass GitLab mittels CI/CD einen Seitengenerator aufruft, um aus Markdown Dateien eine statische Seite zu bauen. Diese Seiten sind dann zum Beispiel unter [gruppe].pages.example.com/[projekt]/ zu erreichen. Aktuell habe ich es noch im Experimentier- Stadium, da mir einige Dinge noch nicht gefallen. Ein Grund ist zum Beispiel ein gutes(!) Theme für Hugo zu finden, welches sich für eine Dokumentation eignet. Aktuell bin ich bei https://docdock.netlify.com/ gelandet. Leider habe ich es so angepasst, dass es auf dem Handy nicht mehr zu gebrauchen ist, wegen dem TOC, das nachträglich eingebaut wurde. Wie auch immer. Pages von GitLab ist eine phantastische Lösung um über Git die Dokumentation zu pflegen. Dank meiner privaten Kenntnisse über Hugo, war es noch leichter das ganze zu implementieren. Jetzt muss ich es nur noch den Kollegen schmackhaft machen, dass es sich lohnt mehr Mühe in die Doku zu stecken, und nicht nur einfach ein copy/paste in ein Wiki zu klatschen.