Seite wählen

NETWAYS Blog

Unser Weg von Confluence zu BookStack

Wenn ich auf meine bald 15 Jahre bei NETWAYS zurückblicke, haben wir schon das ein oder andere Tool für Dokumentation verschlissen und verwendet. Die Reise ging von TWiki zu Foswiki, nahm eine kleinen Nebenausflug zu Mediawiki und brachte uns vor vielen Jahren letztendlich zu Confluence.

Die Entscheidung für Confluence fußte damals vor allem auf zwei Argumenten. Zum einen waren wir gerade mal 18 Leute und die Lizenzkosten für eine On-Prem-Installation überschaubar, zum anderen hatte Confluence einen sehr stabilen Eindruck gemacht und wir wollten damals von der „Selbstbeschäftigung“ und Plugin-Hölle der anderen Systeme weg, da wir dafür zu viel Zeit verbraten hatten. Kurzum, eigentlich die klassische „Dann kauf ich halt was“-Geschichte. Es wäre auch unfair zu sagen, dass die Entscheidung für Confluence eine schlechte Entscheidung war. Das Tool hat uns viele Jahre treue Dienste geleistet und obwohl schon einige Zeit nicht mehr aktualisiert, lief es bis zum gestrigen Tag ohne größere Zwischenfälle

Warum etwas Neues?

Die Motivation für ein neues Tool hatte sowohl technische als auch fachliche Gründe. Technisch entsprach die zunehmende Cloud-Only-Strategie von Atlassian, deren Systeme sich in Vergangenheit auch nicht besonders mit Ruhm bekleckert haben, nicht unseren Vorstellungen, da wir das als elementar angesehene System im On-Prem haben wollten. Hinzu sind die Lizenzkosten mit knapp 90 Leuten durchaus ein Argument sich mal etwas anderes anzusehen und ggf. damit einhergehende Aufwände die Berechtigung zu verschaffen.

Auf der anderen Seite hatten wir auch fachliche Argumente, welche für einen Neuaufbau des Systems gesprochen haben. Unser in die Jahre gekommenes Confluence hatte dringend mal einen Frühjahrsputz nötig und gleichzeitig wollten wir mit einem Handbuch gleich alle Unternehmensprozesse und Regelungen fit für ein späteres Audit machen. Persönlich favorisierte ich die Idee alles in ein System zu packen, was mir unsere Heads jedoch in der Diskussion ausredeten. Im Nachhinein klar die richtige Entscheidung, da ein Handbuch schlichtweg andere Anforderungen hat als ein Dokumentationssystem. Somit haben wir jetzt zwei Systeme (Handbook & Docs) mit unterschiedlichen Anforderungen. Das Handbook ist die „Gesetzgebung“ unserer Firma und das für alle verbindliche Regelwerk. Die Docs spiegeln die Arbeitsdokumente der einzelnen Abteilungen wieder und unterscheiden sich somit signifikant von unserem Handbook.

Wieso nun BookStack?

Von Confluence kommend waren die Anforderungen gar nicht so klein. LDAP sollte gehen, individualisierter PDF-Export, Berechtigungen für Extern und Intern, Zeichnungen sollen direkt im Wiki möglich sein, eine API um technische Informationen (bspw. Kunden im NWS-Umfeld) automatisch zu erstellen und natürlich eine gute Suche und Top-Performance. Nach etwas Recherche bin ich immer wieder über zwei Systeme gestolpert, Wiki.js und BookStack. Beide Systeme sind Open Source und machten in ersten Tests mit Docker einen guten Eindruck. Wiki.js war das auf den ersten Blick modernere System und in vielen Punkten sehr ähnlich zu Confluence. Wenn ich ehrlich bin, weiß ich nicht mehr genau, welches Hauptargument gegen den Einsatz von Wiki.js gesprochen hat. Gründe dagegen waren jedoch, dass das ein oder andere Feature für Version 3.0 angekündigt war, deren Milestone immer verschoben wurde und bis heute nicht verfügbar ist. Auch die Tatsache, dass es Confluence sehr ähnlich war, schreckte mich final davor zurück.

Das Hauptargument Wiki.js nicht zu nehmen, war jedoch nicht Wiki.js sondern BookStack. Auf BookStack bin ich bei der Recherche immer wieder gestoßen, hatte es jedoch nie ernsthaft in Betracht gezogen. Mir schienen die Features nicht ausreichend für unsere Bedürfnisse und darüber hinaus hielt ich die feste Struktur von BookStack, welches die Idee hat ein virtuelles Bücherregal darzustellen, für unzureichend. Im Nachhinein hat sich gerade diese Struktur als einer der größten Pluspunkte herausgestellt und daher bin ich bis heute froh, dass wir uns für BookStack entschieden haben. Darüber hinaus hat uns der pragmatische und sehr aufgeräumte Ansatz von BookStack und die permanente Weiterentwicklung überzeugt.

Was macht BookStack aus?

Ziel es Blogposts soll es nicht sein, verschiedene Wiki- und Dokumentationslösungen miteinander zu vergleichen (vielleicht kommt das mal zu einem späteren Zeitpunkt, aber derartige Artikel gibt es sowieso wie Sand am Meer), sondern eher was uns dazu motiviert hat, den Weg mit BookStack zu gehen und wie wir es umgesetzt haben.

Wie bereits oben angesprochen, stellt BookStack ein virtuelles Bücherregal zur Verfügung und ordnet seine eigentlichen Dokumente, bei BookStack Pages genannt, in eine feste Struktur. Es gibt Shelves, Books und Pages, das wars. Bei Bedarf können Pages noch in so genannte Chapter gruppiert werden, was jedoch optional ist. Genau da steckt aus meiner Sicht ein großer Vorteil von BookStack. Das System verbietet einfach endlose Seitenhierarchien aufzubauen, in welchen sich nach kurzer Zeit keiner mehr zurechtfindet. Die flache und vorgegebene Struktur zwingt einen bei Erstellung der Dokumente über den richtigen Ort nachzudenken und gibt dem ganzen System eine solide Grundordnung. Wir repräsentieren heute jeden Unternehmensbereich in einem eigenen Shelf und abstrahieren die fachlichen Strukturen dann in darunter liegenden Books. Darüber hinaus liefert die Suche auch sehr gute Ergebnisse und Dokumente sind im Vergleich zu unserem vorherigen System schnell zu finden. Auch alle anderen genannten Anforderungen hat BookStack erfüllt und neben LDAP, Zeichnungen, PDF-Export und API geht eigentlich alles, was wir so brauchen. Der Editor kann sowohl im WYSIWYG- als auch im Markdown-Modus verwendet werden, was den Bedürfnissen unserer Mitarbeiter:innen entsprechend entgegenkommt.

Wie haben wir den Umzug gemacht?

Den Teil des Handbooks haben wir zu 95% neu geschrieben. Zum einen waren viele Regelungen und Informationen nicht einheitlich bzw. überhaupt nicht vorhanden. Zum anderen war uns wichtig, dass die Dokumente gleich die entsprechenden Vermerke für eine spätere ISO-Zertifizierung beinhalten. Hinzu war entscheidend, dass wir Dinge wie Stellenbeschreibungen, Unternehmensstruktur und Übersicht aller Mitarbeiter:innen automatisch erstellen. Auch die jeweiligen Assets, welche wir in Snipe-IT verwalten, sollten entsprechend ausgelesen und in den Seiten dargestellt werden. Den Teil der dynamischen Generierung haben wir dann mit Python und Verwendung der API realisiert. Das Ganze läuft nun seit gut 6 Monaten ohne größere Schwierigkeiten.

Die API bietet für nahezu alle Bedürfnisse geeignete Endpunkte und ist sehr gut dokumentiert. Unter Verwendung von entsprechenden Tokens werden die Benutzerberechtigungen so an den API-Consumer weitergereicht.

Bei der Dokumentation der einzelnen Bereiche sah das ganze schon anders aus. Auch hier haben wir viele Dokumente neu geschrieben bzw. manuell übernommen. Gerade die ein oder andere Dokumentation, welche bereits vor 10 Jahren erstellt wurde, schien uns als PDF-Export vollkommen ausreichend archiviert und die manuelle Übernahme wäre eher einer Beschäftigungstherapie gleichgekommen.

In Summe haben wir gemeinsam tausende an Dokumenten gesichtet, migriert, gelöscht und neu geschrieben, aber der Aufwand hat sich gelohnt. Der alte Schrott ist weg und wir finden uns in BookStack nun gut zu recht. Die letzten Abteilungen haben ihre Daten noch unter Verwendung von Confluence Exports umgezogen und gestern haben wir das Altsystem in den wohlverdienten Ruhestand geschickt.

Was noch kommt?

Falls Interesse besteht, kann ich zu einem späteren Zeitpunkt gerne noch etwas über unsere Generatoren schreiben. Diese erzeugen nämlich nicht nur die Seiten für Mitarbeiter:innen und Assets, sondern legen auch Übersichtsseiten mit Sozialleistungen und Regelungen an, welche wir auf Basis der Page-Tags generieren. Auch Consulting könnt ihr jederzeit bei uns kaufen. So richtig etabliert haben wir das im Professional Services noch nicht, aber dann komme eben ich vorbei. Noch kenne ich mich aus 🙂

Darüber hinaus werden wir BookStack aller Wahrscheinlichkeit nach in unser NWS-Portfolio übernehmen, da es eine sehr gute Ergänzung zu unseren bestehenden Produkten darstellt. An dieser Stelle auch ein herzlicher Dank an Dan Brown, welcher in Vollzeit an BookStack arbeitet und es als Open Source Software zur Verfügung stellt. Zur Unterstützung des Projekts haben wir einen Supportvertrag abgeschlossen, den wir bisher jedoch noch nie benötigt haben. Auch ein weitergehendes Engagement wird vermutlich bald kommen, aber dazu später mehr.

Fazit

Confluence hat uns einen guten Dienst erwiesen, aber auf Basis von BookStack und dank der Mitarbeit aller haben wir nun eine neue und modulare Basis für unser Handbook und Dokumentation. Jeder manuelle Schritt und die Überarbeitung waren der Qualität zuträglich und haben uns besser gemacht. BookStack hat sich darüber hinaus als unglaublich stabiles und innovatives Produkt erwiesen, welches ich Euch nur ans Herz legen kann. Für mich die Alternative zu Confluence schlechthin.

Bernd Erk
Bernd Erk
CEO

Bernd ist Geschäftsführer der NETWAYS Gruppe und verantwortet die Strategie und das Tagesgeschäft. Bei NETWAYS kümmert er sich eigentlich um alles, was andere nicht machen wollen oder können (meistens eher wollen). Darüber hinaus startete er früher das wöchentliche Lexware-Backup, welches er nun endlich automatisiert hat. So investiert er seine ganze Energie in den Rest der Truppe und versucht für kollektives Glück zu sorgen. In seiner Freizeit macht er mit sinnlosen Ideen seine Frau verrückt und verbündet sich dafür mit seinen beiden Söhnen und seiner Tochter.

Things done wrong: Dokumentation

Homer Simpson
Nachdem ich letztens in einem Meeting den Hattrick im „Salz in die Wunde“ streuen geschafft habe, als ich auf die Frage ab wann ein System als produktiv gilt geantwortet habe: „Sobald es dokumentiert ist, gesichert und überwacht wird“, wollte ich mich diesmal dem Thema Dokumentation annehmen. Eigentlich ein simples Thema (das für mich zu jedem Projekt dazugehört) kann hier doch viel schief laufen.
Der Inhalt ist meist die einfachste Hürde. Hier hilft es sich im Vorfeld einfach über Zielgruppe und Ziel einig zu sein. Der Unterschied beispielsweise zwischen Installationsdokumentation für den Administrator oder Betriebshandbuch für die Hotline ist doch relativ groß. Bei der Installationsdokumentation sammelte ich üblicherweise nur die ausgeführten Befehle in Themenblöcken und erkläre nur grob warum und wieso, da grundsätzliche Kenntnisse der Funktion vom Linuxadministrator erwarte. Ein Betriebshandbuch ist dagegen ein ganz andere Sache, notfalls fange ich sogar mit Erklärungen an was den Linux überhaupt so ist und sammle Screenshots zu den wichtigsten graphischen Funktionen. Was ich auf alle Fälle allerdings vermeide ist es frei verfügbare Dokumentation unnötig zu duplizieren. Die meisten „Open Source“-Projekte liefern auch hier sehr gute Arbeit ab und halten diese auch aktuell, was oftmals bei eigener Dokumentation nicht der Fall ist oder zumindest zusätzlichen Aufwand bedeutet. Warum dies meist so ist, soll das Hauptthema dieses Blogposts sein.
mehr lesen…

Dirk Götz
Dirk Götz
Principal Consultant

Dirk ist Red Hat Spezialist und arbeitet bei NETWAYS im Bereich Consulting für Icinga, Puppet, Ansible, Foreman und andere Systems-Management-Lösungen. Früher war er bei einem Träger der gesetzlichen Rentenversicherung als Senior Administrator beschäftigt und auch für die Ausbildung der Azubis verantwortlich wie nun bei NETWAYS.

TWiki lokal installieren

Neulich hatte ich ja schon mal einen Post geschrieben, dass Wikis eine sehr praktische Sache zum Ablegen von Texten oder Dokumentationen sind. Einen Nachteil haben sie aber in der Regel: Da es sich um eine Webanwendung handelt, braucht man auch einen Internetzugang um darauf zugreifen zu können. Eine Alternative wäre es, dass Wiki zusammen mit einen lokalen Webserver zu installieren und dann einfach via http://localhost darauf zuzugreifen. Auch dafür empfiehlt sich TWiki, da es im Gegensatz zu MediaWiki keinen zusätzlichen SQL Server braucht. Praktisch, dass es auf der TWiki Download Page auch Pakete für Windows oder Mac OS X gibt.

Julian Hein
Julian Hein
Executive Chairman

Julian ist Gründer und Eigentümer der NETWAYS Gruppe und kümmert sich um die strategische Ausrichtung des Unternehmens. Neben seinem technischen und betriebswirtschaftlichen Background ist Julian häufig auch kreativer Kopf und Namensgeber, beispielsweise auch für Icinga. Darüber hinaus ist er als CPO (Chief Plugin Officer) auch für die konzernweite Pluginstrategie verantwortlich und stösst regelmässig auf technische Herausforderungen, die sonst noch kein Mensch zuvor gesehen hat.

Welches Wikisystem für das Intranet?

In dem Blogartikel Einfachere Dokumentation durch Wikis vor ein paar Tagen hatte ich geschrieben, dass sich ein Wikisystem sehr gut für die Ablage von IT Dokumentation eignet und welche Vorteile ein solches Wikisystem dafür bietet. Heute geht es darum welches System am besten geeignet ist:
Das bekannteste ist sicher MediaWiki, denn es kommt bei der Wikipedia zum Einsatz. Jetzt könnte man folgern, dass es damit auch für den internen Einsatz prädestiniert ist. Das ist aber nicht der Fall, denn MediaWiki wurde ganz speziell für die Wikipedia und deren Bedürfnisse entwickelt. Es ist vor allem auf eine sehr große Anzahl von Artikeln, Redakteuren und Leser optimiert und es liegt ein großer Fokus auf dem Schutz vor Vandalismus. Diese Features und ein rein auf Lexikonartikel optimiertes System werden aber in einem Firmenintranet nicht wirklich benötigt. Auf der anderen Seite fehlen in MediaWiki aber wichtige Collaboration Funktionen wie geschützte Bereiche, Ablage von Binärdateien oder Workflows.
Wesentlich besser geeignet sind TWiki oder Dokuwiki. Beide haben Features, die viel besser zur Ablage von Dokumentationen passen. Neben den normalen Grundfunktionen jeden Wikis, sind das vor allem eine wesentlich bessere Unterstützung für hierarchische Inhalte, Kategorien und Order. Die Inhalte lassen sich in diesen beiden Systemen einfach wesentlich besser strukturieren. Zugriffsregelungen erlauben es Teilbereiche des Wikis nur für bestimmte User freizugeben, so dass Arbeitsgruppen oder Abteilungen ihre eigenen, geschützten Bereiche einrichten können. Und zuletzt verfügen beide über einen Plugin Mechanismus, mit dem sich die Funktionen der beiden Wikis noch wesentlich erweitern lassen. Selbst kleinere Webanwendungen wie ein Ticket- oder ein Inventarsystem lassen sich so innerhalb des Wikis einfach nachrüsten.
Fazit: MediaWiki ist zwar das bekanntere System, es ist aber für ein online Lexikon optimiert. Dokuwiki und TWiki sind wesentlich besser für den Einsatz in einem Intranet geeignet, denn sie bieten viel weitergehende Funktionen.

Julian Hein
Julian Hein
Executive Chairman

Julian ist Gründer und Eigentümer der NETWAYS Gruppe und kümmert sich um die strategische Ausrichtung des Unternehmens. Neben seinem technischen und betriebswirtschaftlichen Background ist Julian häufig auch kreativer Kopf und Namensgeber, beispielsweise auch für Icinga. Darüber hinaus ist er als CPO (Chief Plugin Officer) auch für die konzernweite Pluginstrategie verantwortlich und stösst regelmässig auf technische Herausforderungen, die sonst noch kein Mensch zuvor gesehen hat.

Einfachere Dokumentation durch Wikis

In vielen unserer Projekten entsteht immer wieder die Anforderung nach einem (neuen) Dokumentationssystem. Entweder weil der Kunde noch gar nichts in diesem Bereich einsetzt oder mit dem bestehenden System unzufrieden ist. Wir benutzen selbst ein Wiki und empfehlen das auch unseren Kunden. Aus mehreren Gründen:

  • Dokumentation ist in der Regel eine sehr unbeliebte Aufgabe, die kein Administrator gerne erledigt. Folglich sollten die Einstiegshürden möglichst niedrig und die Dokumentation mit möglichst wenig Arbeit verbunden sein. Wikis sind webbasiert, einfach zu erreichen, leicht zu bedienen und damit einfach schneller als andere Systeme. Je schneller und einfacher es für einen Admin ist einen Change zu dokumentieren, umso höher ist die Wahrscheinlichkeit, dass es auch gemacht wird.
  • Durch die flexible Struktur eines Wikis, können auch neue Bereich oder Themen einfach eingepflegt werden, ohne auf eine komplizierte Hierarchie Rücksicht zu nehmen. Es ist immer noch besser der Inhalt ist drinnen, aber an der falschen Stelle, als gar nicht eingepflegt. Die Inhalte können immer noch später umsortiert werden.
  • Im Gegensatz zu anderen Alternative ist eine Suchfunktion bereits out-of-the-box eingebaut und muss nicht extra implementiert werden. Inhalte lassen sich so auch ohne absolute Ordnung leicht wiederfinden.
  • Die meisten Wikisysteme gestatten die Anbindung externer Authentifizierungsmechanismen, so dass keine zusätzlichen Useraccounts oder Passwörter verwendet werden müssen. Im internen Netz kann die Anmeldung durch Kerberos vielleicht sogar komplett entfallen.
  • Die Versionierung der Wikiartikel erlaubt es später Änderungen an der Dokumentation nachzuvollziehen oder einfach auf einen alten Stand zuzugreifen. Fehler und versehentliche Löschungen können so jederzeit einfach wieder rückgängig gemacht werden. Ebenso können Diffs erstellt werden, die genau alle Änderungen zwischen zwei Versionsständen wiedergeben.
  • Da das System HTML basiert ist, lassen sich die Inhalte einfach über normale Hyperlinks in anderen Anwendungen verlinken. Beispielsweise kann man in Nagios Links direkt zur Dokumentation der jeweiligen Ressource einbauen.
  • Die meisten Wikis sind Open Source und können deswegen einfach angepasst werden, wenn es später individuelle Zusatzanforderungen an das Wiki geben sollte. Ganz zu schweigen von den wegfallenden Lizenzkosten.

Natürlich sollte man nicht verschweigen, dass ein Wiki auch ein paar Nachteile mit sich bringt: In der Regel kann jeder alle Texte einsehen oder verändern und es ist schwierig in einem Wiki genaue und vor allem verbindliche Strukturen vorzugeben. Wobei das in einer offenen, wissensbasierten Firma nicht wirklich ein Nachteil sein muss.
In Summe überwiegen also definitiv die Vorteile eines Wikis und ich werde in ein paar Tagen die wichtigsten und bekanntesten Wiki Systeme vorstellen und ihre jeweiligen Vor- und Nachteile als Dokumentationssysteme erläutern.

Julian Hein
Julian Hein
Executive Chairman

Julian ist Gründer und Eigentümer der NETWAYS Gruppe und kümmert sich um die strategische Ausrichtung des Unternehmens. Neben seinem technischen und betriebswirtschaftlichen Background ist Julian häufig auch kreativer Kopf und Namensgeber, beispielsweise auch für Icinga. Darüber hinaus ist er als CPO (Chief Plugin Officer) auch für die konzernweite Pluginstrategie verantwortlich und stösst regelmässig auf technische Herausforderungen, die sonst noch kein Mensch zuvor gesehen hat.