Die stetige Erweiterung unserer Software und der damit verbundenen Programmiersprache machte die manuelle PDF-Dokumentation unhaltbar. Um Diskrepanzen zwischen Produkt und Dokumentation zu vermeiden, entschieden wir uns für ein eigenes Dokumentationswerkzeug auf Basis des MediaWikis. Die Wahl basierte auf dessen Open-Source-Etablierung, der garantierten Weiterentwicklung durch Wikipedia und der Fülle an Vorlagenbeispielen. Durch systematische Kategorisierung, Vorlagenentwicklung und feste Artikelstrukturen entstand eine effiziente, stets aktuelle und leicht erweiterbare Wissensplattform, die auch neuen Mitarbeitern die Einarbeitung erleichtert. 
Entwicklung eines eigenen Dokumentationswerkzeuges für unser Unternehmen
Warum brauchten wir ein neues System, um unsere Produkte zu dokumentieren?
Als Softwareentwickler kennen wir die Herausforderung: Sie schaffen ein leistungsstarkes Produkt, das sich – wie in unserem Fall – in einer eigenen, spezifischen Sprache programmieren lässt. Doch mit der stetigen Weiterentwicklung und der regelmäßigen Erweiterung des Funktionsumfangs wächst auch die Komplexität der Dokumentation exponentiell an. Ich stand vor genau diesem Problem. Unsere bisherige Dokumentation, sorgfältig in PDF-Form erstellt, konnte dem rasanten Tempo der Neuerungen einfach nicht mehr standhalten. Jede Funktionserweiterung bedeutete einen erheblichen Aufwand, die bestehenden PDFs zu aktualisieren, neu zu formatieren und dann an die Kunden auszuliefern.
Das Ergebnis war oft eine Diskrepanz zwischen der aktuellen Softwareversion und der verfügbaren Dokumentation. Dies führte nicht nur zu Frustration auf der Seite des Kunden, sondern auch zu einem erhöhten Supportaufkommen bei uns im Unternehmen. Wir brauchten eine dynamische und flexible Lösung, die es uns ermöglichte, die Dokumentation kontinuierlich und nahtlos zu erweitern und gleichzeitig sicherzustellen, dass unsere Kunden stets Zugriff auf die aktuellste Version haben. Ein eigenes Wiki bot sich als die ideale Antwort an, um diese Lücke zu schließen und unseren Kunden eine stets aktuelle und zugängliche Wissensbasis zur Verfügung zu stellen.
Warum MediaWiki unsere neuen Dokumentationsplattform wurde
Als ich mich der Herausforderung stellte, eine zukunftsfähige Dokumentationslösung zu etablieren, stand ich vor einer Vielzahl an Optionen. Von flexiblen Content-Management-Systemen wie WordPress über spezialisierte Wiki-Software wie TikiWiki bis hin zu professionellen Publishing-Tools wie FrameMaker – der Markt bot zahlreiche Möglichkeiten. Meine Entscheidung fiel jedoch nach reiflicher Überlegung auf MediaWiki, und das aus gutem Grund.
Die Wahl fiel auf MediaWiki, da es sich in der Open-Source-Gemeinschaft sowie in der Unternehmenswelt bereits als äußerst robust und zuverlässig etabliert hat. Ein entscheidender Faktor, der die langfristige Sicherheit unserer Investition untermauert, ist die Nutzung von MediaWiki durch die Wikipedia selbst. Dies garantiert de facto eine kontinuierliche Weiterentwicklung und Pflege der Software, da eine der größten Wissensplattformen der Welt auf ihre Stabilität und Funktionalität angewiesen ist.
Zudem bot mir die Fülle an existierenden Beispielen – sei es in Form von Vorlagen oder Artikelstrukturen – einen unschätzbaren Vorteil beim Aufbau unseres eigenen Wikis. Ich konnte von der Best Practices der Wikipedia lernen und diese adaptieren. Nicht zuletzt ist die umfangreiche Dokumentation zur Vorlagenprogrammierung ein weiterer Pluspunkt, der mir die nötige Flexibilität für die individuelle Gestaltung und Anpassung unserer Inhalte bietet. Diese strategische Entscheidung ermöglichte es mir, eine leistungsstarke und nachhaltige Dokumentationsplattform zu schaffen, die den Anforderungen unserer dynamischen Softwareentwicklung gerecht wird.
Wie ich die Dokumentationsplattform (MediaWiki) systematisch implementierte
Die reine Installation von MediaWiki auf einem Webserver ist nur der erste Schritt. Für eine wirklich effektive und nachhaltige Dokumentationslösung bedarf es eines durchdachten Konzepts, wie Wissen im Wiki strukturiert und dokumentiert werden soll. Genau hier setztee ich an, um sicherzustellen, dass unser Wiki nicht nur ein Sammelsurium an Informationen wird, sondern eine kohärente und leicht zugängliche Wissensdatenbank.
Mein Ansatz basierte auf einer klaren Kategorisierung des gesamten Wissens. Ich unterteilte unsere Inhalte in verschiedene Hauptkategorien, darunter „Anleitungen“, „Schlüsselwörter“, „Programme“, „Sonstiges“ und viele weitere spezifische Bereiche. Dieser systematische Aufbau ermöglicht eine intuitive Navigation und stellt sicher, dass Benutzer die gesuchten Informationen schnell finden.
Analog zur bewährten Praxis der Wikipedia habe ich für jede dieser Kategorien spezifische Vorlagen konzipiert und entwickelt. Dies umfasste eine Vielzahl von Elementen: von Infoboxen für Metadaten über Vorlagen für Verzeichnisstrukturen, Quellcode-Darstellungen und standardisierte Verlinkungen bis hin zu vielen weiteren nützlichen Bausteinen. Darüber hinaus erstellte ich eine vorgefertigte Artikelstruktur, die bereits essentielle Elemente wie Infoboxen und definierte Absatztypen enthielt.
Diese methodische Vorgehensweise hatte zwei entscheidende Vorteile: Zum einen ermöglichte sie uns, neue Artikel äußerst zügig zu erstellen, da der Grundaufbau bereits vorgegeben war. Zum anderen senkte sie die Einarbeitungsschwelle für neue Mitarbeiter erheblich. Dank der klaren Struktur und der intelligenten Vorlagennutzung konnten sich auch weniger erfahrene Anwender schnell im Wiki zurechtfinden und qualitativ hochwertige Beiträge leisten. Das Ergebnis ist eine konsistente, leicht erweiterbare und benutzerfreundliche Dokumentationsplattform, die die Software-Erfahrung unserer Kunden nachhaltig verbesserte.
Beispiel einer Kopiervorlage aus unserem Wiki
{{FreigabeBegin | Page | pruefen = N | inhalt = N | rechtschr = N | technisch = N | datum = }}
{{Kommentar | {{{Falls der Seitenname Unterstriche enthält oder mit einem Kleinbuchstaben beginnen soll, ist "{{PAGENAME}}" durch den anzuzeigenden Namen zu ersetzen.}}} }}
{{SEITENTITEL: {{PAGENAME}} }}
{{InfoboxSWJobkarte
| Schlüsselwort = «Schlüsselwort in Großbuchstaben, variable Teile klein (KxPAPIERy)»
| GehoertZuPgm = «Name des Programms, zu dem das Schlüsselwort gehört.»
| GehoertZuMod1 = «Module, zu denen das Schlüsselwort gehört. (Maximal 5)»
| SeitVersion = «Programmversion, ab der das Schlüsselwort unterstützt wird.»
| SeitDatum = «Datum, seit dem das Schlüsselwort unterstützt wird.»
| Verwendung1 = «Dateiformate, in denen das Schlüsselwort verwendet wird (mac, spl etc.). (Maximal 5)»
| HinweisWeitereParameter = «Hinweis auf weitere Parameter (siehe Schlüsselwort MAILING (Dokustream)).»
| WeitereProgramme1 = «Programme, die gleichnamige Schlüsselwörter kennen. Das "Hauptprogramm" muss ggf. als erstes stehen. (Maximal 5)»
{{Kommentar | * | {{{Parameter 1 von max. 7}}} }}
| Par1_WdhBisMax = «Gibt die maximale Parameternummer bei Wiederholungen an (s. Schlüsselwort SPLITVG), sonst leer.»
| Par1_Name = «Parameterbezeichnung.»
| Par1_Pflicht = «J = Parameter ist Pflichtangabe; N = Parameter ist optional»
| Par1_Syntax_Zusammen = «Nur bei optionalen Parametern: Gibt an, ob, wenn dieser Parameter gesetzt wird, auch der folgende gesetzt werden muss oder sollte.»
| Par1_Beschreibung = «Beschreibung, was der Parameter beinhaltet oder bewirkt.»
| Par1_Datentyp = «S = Zeichenkette; O = Zeichenk. ohne ""; R = Pfad; Z = Datum; T = Datum mit TODAY; D = Dezimalzahl; W = Ganzzahl; A = Schreibmodus; B = Boolescher Wert»
| Par1_WertebereichVon = «"von" eines Von-Bis-Wertebereich. Kann mit Werteliste kombiniert werden.»
| Par1_WertebereichBis = «"bis" eines Von-Bis-Wertebereich. Kann mit Werteliste kombiniert werden.»
| Par1_WertebereichWert1 = «Liste erlaubter Werte. Kann mit Von-Bis-Bereich kombiniert werden. (Maximal 8)»
| Par1_WertebereichText = «Beschreibender Text wie z. B. "Alle Beilagenkennungen aus der Datei beilagen.txt". Wird nicht angezeigt, wenn Von-Bis-Bereich oder Werteliste angegeben ist.»
| Par1_WertebereichMaxLen = «Max. Länge für Strings. Wird nur angezeigt, wenn keine anderen Angaben gemacht werden. Default: 255.»
}}
{{Kommentar | {{{Der folgende Text (zumindest der Anfang) wird beim Zeigen auf einen Link auf diese Seite als Vorschau angezeigt.}}} }}
«Einleitender Text (Verwendung des Schlüsselwortes).»
{{Headline | 1 | Syntax | Gross = N}}
{{SyntaxBeschreibung | Bsp = «Beispielzeile» | Var1 = «1. variabler Teil» | Text1 = «1. Wertebereich» | Var2 = «2. variabler Teil» | Text2 = «2. Wertebereich»}}
{{Headline | 1 | Arbeitsweise | Gross = N | Leer = J}}
{{Kommentar | {{{Eingaben, Ausgaben, Konfigurationen. Auch ein Programmablaufplan wäre nicht schlecht.}}} }}
{{Headline | 2 | {{- | Parameter «n»}} («Name») | Gross = N | Leer = J}}
{{Kommentar | {{{Wenn es Sinn macht: Pro Parameter ein Abschnitt mit Bedeutung und Funktionsweise (Zusammengehörende Parameter in einem Abschnitt zusammenfassen).}}} }}
{{Headline | 2 | Fehlersituationen | Gross = N | Leer = J}}
{{Kommentar | {{{Was kann bei Fehlerhafter Verwendung des Schlüsselwortes passieren? Auch Fehlernummer und Auszug aus der Log-Datei angeben.}}} }}
{{Headline | 1 | Beispiele | Gross = N | Leer = J}}
{{Kommentar | {{{Einfache/konkrete Anwendungen, die dem Verständnis dienen. (Für komplexe Anwendungen zur Projektumsetzung lieber eine Anleitungsseite erstellen.)}}} }}
{{Headline | 1 | Siehe auch | Leer = J}}
{{Kommentar | {{{Auflistung mit * (ohne Gliederung) bzw. ** (mit Gliederung). Bei Bedarf Gliederungspunkte einkommentieren.}}} }}
{{Kommentar | * Anleitungen}}
{{Kommentar | * Anderes}}
{{Headline | 1 | Weblinks | Leer = J}}
{{Headline | 1 | Literatur | Leer = J}}
{{Headline | 1 | Einzelnachweise | Leer = J}}
{{FreigabeEnd}}