Use Case IT-Dokumentation: Projektdokumentation in der Softwareentwicklung mit MediaWiki

Anwendungsfälle für die Nutzung von MediaWiki gibt es viele. Einer davon ist die Nutzung der Wiki Software für IT Dokumentation.
Der folgende Erfahrungsbericht basiert auf einem Gespräch mit Markus Glaser. Er ist Leiter der Softwareentwicklung bei der Hallo Welt! GmbH und beschreibt den Use Case von MediaWiki (mit der „Erweiterung“ BlueSpice) als Software für Projektdokumentation in der Softwareentwicklung.

Hallo Welt! ist ja nicht nur eine Firma, die Wikis entwickelt, sondern auch intern selbst u.a. zur Dokumentation benutzt. Wie sieht das bei Hallo Welt! aus?

Wir nutzen das Wiki nun seit über fünf Jahren in der Firma als übergreifendes Werkzeug für die Sammlung von Wissen und Erfahrung. Genauer gesagt ist es ein MediaWiki mit den neuesten Extensions aus unserem Eigenbau „BlueSpice“. Inhaltlich arbeiten Marketing und IT bzw. Technik am meisten in unserem Wiki. Speziell die IT Abteilung, wenn wir unsere acht Softwareentwickler als solche bezeichnen wollen, nutzt das Wiki jedoch sehr intensiv. Das Wiki als Dokumentationstool ist aus unserem Arbeitsalltag nicht mehr wegzudenken.

IT Abteilungen stehen vor der Aufgabe, Probleme, samt deren Lösungswege aufzuschreiben, und zwar so, dass sie für andere gut verständlich sind. Markus, welche Prozesse werden bei Dir in der Softwareentwicklung hauptsächlich beschrieben?

Code Dokumentation ist natürlich ein wichtiges Stichwort. Aber eben auch technische Erfahrungen und Beschreibungen. Sitzt ein Programmierer drei bis vier Stunden an der Lösung eines Problems, so beschreibt er den Lösungsweg danach im Wiki. Ich denke, die folgenden vier Szenarien kommen in der IT Dokumentation bei uns am häufigsten vor:

    • Wir beschreiben dort einzelne Erweiterungen mit Hilfe von Functional Designs. Diese Beschreibungen enthalten die Funktionsweisen der Extensions, sowie weiterführende Idee für spätere Entwicklungen.
    • Zudem beschreiben wir dort technische Erfahrungen zu allen Technologien, die wir nutzen. Damit sind aber nicht allgemeine Beschreibungen, wie sie beispielsweise auf Wikipedia zu finden sind, gemeint, sondern ganz konket: welche Schwierigkeiten hatten wir mit dem Tool und wie wurden die Probleme gelöst? Sehr schön ist zum Beispiel die Seite über Selenium Tests, also auch Testdokumentation, wo genau solche Erfahrungen drinstehen: „Wenn du dieses oder jenes testen willst, achte darauf. Denn damit hatten wir in der Wiki-Umgebung folgendes Problem. Aber so kannst du es umgehen.“
    • Weiterhin dient das Wiki als Standardisierung. Jeder Mitarbeiter findet hier die „coding conventions“, nach denen er vorzugehen hat. Wie muss der Code geschrieben werden, wie sehen bestimmte Sachen aus, wo sind Leerzeichen, wo Einrückungen usw.
Release Management in MediaWiki
Release Management in MediaWiki
  • Als Letztes und vielleicht wichtigstes Instrument für unsere Projektdokumentation ist der Release Management Plan im Wiki. Hier sind alle Maßnahmen samt aktuellem Status für ein neues Release hinterlegt. Das ist entscheidend für verlässliches Qualitätsmangement. Die Wichtigkeit der Seite sieht man u.a. an der Aktivität, die auf dieser Seite herrscht.

Warum habt Ihr ein Wiki zur Dokumentation gewählt und kein anderes System?

Es erfüllt ideal unsere technischen Anforderungen und unterstützt eine von uns gewollte, spezielle Art des Arbeitens, nämlich kollaborativ. Das gemeinsame Arbeiten an einem Artikel ist dabei das Offensichtlichste. Aber auch Workflow-Prozesse, die Freigaben von einzelnen Extensions für das Release beinhalten, können über das Wiki abgewickelt werden. Ich kann beispielweise Extensions für das neue Release über Freigaben steuern.

Darüber hinaus ermöglicht es das Wiki, dass Mitarbeiter schnell voneinander lernen können und von den Erfahrungen der anderen profitieren. Die einzelnen Expertisen werden so öffentlich und Wissen kann kombiniert werden. Wenn beispielsweise einer der Entwickler ein Problem samt Lösung zum Thema „ELGG“ beschreibt, so kann dies dazu führen, dass der Entwickler, der sich gerade mit einem ähnlichen Problem zum Thema „facebook“ beschäftigt, der eigenen Lösung so viel schneller näher kommt.

Du hast gerade von technischen Anforderungen gesprochen, welche Anforderungen hattet Ihr denn an das System?

Es war wichtig, dass Wissen und Erfahrung aus der Softwareentwicklung zentral an einem Ort gesammelt, verfügbar gemacht und natürlich gefunden wird. Zudem sollte die Möglichkeit gegeben werden, Anleitungen und How to’s möglichst unkompliziert aufschreiben zu können. Und das soll das jeder tun können, und zwar ohne Hürden und ohne großartiges Einarbeiten in neue Systeme. Der WYSIWYG-Editor und das stark vereinfachte Einfügen von Bildern und Dateien sind dahingehend sehr wertvoll. Die Facettensuche und das neue Search-as-you-type sind für das Auffinden von Informationen inzwischen unerlässlich.
Open Source Software sollte es zudem sein und leicht zu warten. Das ist bei MediaWiki ja sowieso die Basis.

Jetzt sprichst Du ja vor allem aus Sicht der Softwareentwicklung, da ist doch Code Dokumentation besonders wichtig, oder?

Code und Erfahrungen können ausführlich dokumentiert werden.
Code und Erfahrungen können ausführlich dokumentiert werden.

Ja, und MediaWiki bietet auch bezüglich von Programmcodes wie beispielsweise SQL Statements oder config-Dateien den Vorteil, dass diese völlig unmodifiziert in das Wiki rein, aber auch wieder rauskommen. Denn in der IT Dokumentationen fallen häufig spezielle technische Beschreibungen und Anweisungen an, oft auch Codes, die eins zu eins abbildbar sein müssen. Diese Codes müssen ohne Veränderungen gespeichert und vor allen Dingen auch ohne Abwandlung exportiert und weiterverwendet werden können. MediaWiki gewährleistet das. Bei Word hingegen kann ich mir eben nicht sicher sein, ob nicht doch irgendwelche Anführungszeichen automatisch verändert werden.

In welchen Phasen verlief denn die Einführung des Wikis?

Anfangs waren es nur wenige Leute in der Technik, das heißt vor allem ich selbst habe sehr viele Inhalte ins Wiki gestellt. Dann kamen mehr Mitarbeiter hinzu und mit ihnen neue Artikel. Aber auch vorhandene Artikel wurden ergänzt, verbessert und ausformuliert. Es folgte eine Phase, in der nur wenig im Wiki gearbeitet wurde, aber durch die steigendenden Entwicklungszahlen auch mehr Dokumentation nötig wurde. Da musste ich reagieren und habe gewisse Arbeitsschritte per Dekret festgelegt. Zu diesen gehört, dass im Wiki dokumentiert wird. Es ist eben nicht nur das wichtig, was man für sich selbst braucht, sondern generell Projektzustände auch für andere nachvollziehbar zu beschreiben. Nachdem das Schreiben ins Wiki mehr oder weniger in den „Arbeitsalltag“ übergegangen ist, läuft es beinahe von allein. Ich muss nur noch selten nachfragen: „Steht das auch schon im Wiki?“. Aktuell haben wir also einen sehr stabilen Status und ehrlicherweise ist es sogar so, dass ohne unser Wiki die Firma nicht so erfolgreich laufen könnte.

Welche Lessons Learned kannst Du weitergeben?

Eine sehr harte Lektion war, dass ich tatsächlich einige Male wirklich gute Ideen nicht ins Wiki geschrieben habe. Das Dokumentieren ging im Alltag unter und diese Ideen sind schlicht weg. Das bedeutet eben auch, dass ich gelernt habe, das Wiki als Notizzettel bzw. Gedächtnisstütze zu benutzen. Dabei sei auch erst mal egal, wie die Form ist, Hauptsache es steht drin. Nach und nach sollte natürlich Kontext hinzukommen, denn ohne Kontext ist eine Information nur schwer verwertbar. Wir haben beispielsweise noch Seiten, da stehen MySQL Schnipsel mit einigen Befehlen drin, die versteht aber nicht jeder. Diese müssten konsequenterweise noch weiter ausgebaut werden.
Was ich für mich persönlich auch mitgenommen habe, ist, dass es einen Träger geben muss, der hinter dem Projekt steht. Derjenige muss, gerade zu Beginn, ab und zu die Peitsche auspacken, – die anderen immer wieder auffordern „Schreib das ins Wiki“. Das reine Angebot, dass es ein Wiki gibt, reicht nicht. Es dauert eben seine Zeit, bis Mitarbeiter selbst die Erfahrung machen und zu der Erkenntnis kommen, dass mit der Nutzung des Wikis Vieles sehr viel einfacher ist.

Woran merkst Du, dass das Wiki, die oben genannten Anforderungen auch wirklich erfüllt?

Auszug aus dem vielgenutzten Portal der Technik
Auszug aus dem vielgenutzten Portal der Technik

Statistik ist das Zauberwort. Also zum einen nutze ich viele, der vom Wiki zur Verfügung gestellten Werkzeuge, die eine Meta-Perspektive ermöglichen. Zum Beispiel sagen mir die Zugriffe auf das Technik-Portal (inzwischen sind das über 10.000 bei 10 Mitarbeitern in 5 Jahren), dass dieses wertvolle Informationen enthält, obwohl dort zunächst ja nur Inhalte verlinkt sind. Auch sehe ich an den „RecentChanges“, dass das Wiki ständig in Bewegung ist. Jeden Tag gibt es neue Änderungen, und wir sind in der Firma ja gerade mal 15 Leute, da ist das sehr beachtlich.
Zum anderen merke ich es an meinen Mitarbeitern, sie wissen, welches Problem der Kollege wie gelöst hat. Sie wissen also, wer Experte ist und sprechen bei Bedarf sofort mit dem richtigen Ansprechpartner für ihr eigenes Problem. Dadurch, dass alle Mitarbeiter an den Beschreibungen arbeiten, sind sie durch viele verschiedene Perspektiven gekennzeichnet, und somit durchdachter und qualitativ hochwertiger.

Was ist das Ziel für die IT Dokumentation in den nächsten 2 Jahren?

Semantifizierung. Ganz klar, Semantik ist das stärkste Tool, das unser Wiki bereitstellt, was aber noch nicht genügend genutzt wird.  Zum Beispiel in Bezug auf die Functional Designs hieße das dann sehr viel schneller Cluster bilden zu können wie „alle die mit Grafik zu tun haben“, „alle die mit MediaWiki 1.19 laufen“ etc. Wir könnten Abfragen und Prozesse stark optimieren, wenn wir die Daten systematisch semantifizieren würden. Das ist definitiv das Ziel, das wir unbedingt umsetzen müssen. Gut, daneben gibt es noch ein paar Aufgaben, die uns zusätzlich bevorstehen, wie zum Beispiel, dass es nun bereits so viele Artikel im Wiki gibt, dass wir dringend mal einige davon löschen oder zumindest archivieren müssen. Generell gilt: noch mehr Ordnung schaffen.

 

Vielen Dank für das Gespräch, Markus Glaser.

Am 1. März 2013 findet in Regensburg der Workshop “ IT-Projektmanagement in Zusammenarbeit mit großen Unternehmen“ statt. Nähere Informationen und Anmeldung.
Sie benötigen Hilfe bei der Umsetzung ihrer IT Dokumentation mit MediaWiki oder haben einen Anwendungsfall? Dann kontaktieren Sie uns:
Kontakt mit Hallo Welt! oder koepff@hallowelt.com

BlueSpice pro als Lösung für IT Dokumentation

Weitere Use Cases:

 

 

 

Dies könnte Ihnen auch gefallen

2 Kommentare

Schreiben Sie einen Kommentar