Die Wissensdatenbank: Euer bester Freund als Technical Writer

Ihr kennt das Gefühl, wenn man vor einem Berg von Informationen steht und nicht weiß, wo man anfangen soll.
Als Technical Writer ist dies euer „täglich Brot“.

Aber was, wenn ihr ein Werkzeug hättet, das euch hilft, diesen Berg zu bezwingen? Genau darum geht’s heute: Wir tauchen in die Welt der Wissensdatenbanken ein und schauen, wie sie euch im Job als Technical Writer unterstützen.

Eine Wissensdatenbank ist wie ein digitales Gehirn für eure Firma, euer Team und/oder eure Projekte. Sie sammelt, strukturiert und bewahrt das gesamte Wissen, das ihr für die Erstellung eurer Dokumentation benötigt. Von technischen Spezifikationen über Anleitungen bis hin zu den Hintergründen, hier findet ihr alles an einem Ort. Das spart nicht nur Zeit, sondern sorgt auch dafür, dass eure Dokumente immer präzise und aktuell sind. Wenn sie jemand pflegt. 😉

Was ist eine Wissensdatenbank eigentlich?

Stellt euch eine Wissensdatenbank als eine Art zentrales Archiv vor. Sie ist eine Sammlung von Informationen, die in einer organisierten, durchsuchbaren Form vorliegen. Das Besondere daran: Sie ist für jeden im Team zugänglich.

Die Idee dahinter: Ob es um die neuesten Produkt-Features, die richtigen Begriffe oder die gängigen Fehler geht, anstatt bei jedem Problem eine E-Mail zu schicken oder in alten Chats zu wühlen, schaut ihr einfach in die Datenbank. Das macht euch nicht nur effizienter, sondern auch zu wahren Wissensmanagern.

Technische Spezifikationen: Das Herzstück eurer Arbeit

Wenn ihr eine Wissensdatenbank aufbaut, sind die technischen Spezifikationen das A und O. Hier sammelt ihr alle wichtigen Details zu den Produkten oder Systemen, über die ihr schreibt. Denk an Dinge wie:

Architektur-Diagramme: Wie hängen die verschiedenen Komponenten zusammen?
API-Dokumentation: Welche Endpunkte gibt es und wie funktionieren sie?
Funktionsbeschreibungen: Was kann das Produkt und wie ist die Logik dahinter?

Indem ihr diese Informationen zentral speichert, stellt ihr sicher, dass jeder, der an der Dokumentation arbeitet, auf dem gleichen Stand ist. Das verhindert Fehler und spart unendlich viele Abstimmungsrunden.

Die richtigen Tools für eure Wissensdatenbank

Euer Erfolg beim Aufbau einer Wissensdatenbank hängt maßgeblich von den richtigen Werkzeugen ab. Je nach Projektgröße und Team-Workflow gibt es verschiedene Lösungen, die für euch in Frage kommen. Manche Tools setzen auf einfache Auszeichnungssprachen wie Markdown, während andere als All-in-One-Lösungen alle Schritte der Dokumentation abdecken.

Gängige Office Tools wie Word/Google Docs/Notepad++ helfen euch beim schreiben, sind aber danach dann als Einzeldateien irgendwo abgelegt und auch eine Suche über diverse Dokumente wäre nicht ideal. Für bessere Visualisierung nutzt man auch häufig Tools aus dem Adobe Portfolio (Illustrator, Photoshop, InDesign, etc.) Das alles muss aber möglichst konsistent, strukturiert und zugänglich abgelegt werden, damit später idealerweise kein großer Aufwand mehr erforderlich ist, diese Inhalte für die Nutzer bereit zu stellen.

Schauen wir uns also exemplarisch einige der gängigsten Optionen an, die Technical Writer heute dabei unterstützen können.

1. Markdown & Docs-as-Code

Was ist das? Markdown ist eine extrem einfache und intuitive Auszeichnungssprache. Ihr schreibt eure Texte mit einer minimalen Formatierung in einfachen Textdateien und könnt sie dann in HTML umwandeln. In Kombination mit einem Versionskontrollsystem wie Git ist das die Basis für einen „Docs-as-Code“-Ansatz, bei dem die Dokumentation wie Software behandelt wird.
Vorteile:
- Simpel und schnell: Markdown ist so einfach, dass es jeder sofort versteht. Ideal für kurze, schnelle Notizen oder Dokumente, an denen auch Entwickler mitarbeiten.
- Versionskontrolle: Jede Änderung wird nachverfolgt. Ihr seht immer, wer wann was geändert hat und könnt bei Bedarf zu einer früheren Version zurückkehren.
- Kollaboration: Entwickler und Technical Writer können in der gleichen Umgebung (z.B. Git) zusammenarbeiten.
Nachteile:
- Eingeschränkte Formatierung: Für komplexe Layouts, Tabellen oder spezielle Formatierungen ist Markdown oft nicht ausreichend.
- Kein zentrales Management: Ohne zusätzliche Tools (wie ein statischer Website-Generator) ist es schwierig, eine komplexe Wissensdatenbank zu managen.

Markdown Tools gibt es quasi für alle Plattformen und in diversen Variationen:

Mac: MacDown, iA Writer, oder Marked 2 iOS / Android: iA Writer Windows: ghostwriter oder Markdown Monster Linux: ReText oder auch den ghostwriter Web: Dillinger oder StackEdit

2. AsciiDoc & Docs-as-Code

Was ist das? AsciiDoc ist eine mächtigere Alternative zu Markdown. Es ist ebenfalls eine einfache Auszeichnungssprache, die aber deutlich mehr Funktionen für die technische Dokumentation bietet. Auch hier ist die Idee, die Dokumentation in Textdateien zu schreiben und sie über Versionskontrollsysteme zu verwalten.
Vorteile:
- Umfassende Syntax: AsciiDoc unterstützt Funktionen wie Querverweise, Variablen, bedingte Texte und komplexe Tabellen. Ideal für professionelle und umfangreiche Dokumentationen.
- Wiederverwendbarkeit: Ihr könnt Textbausteine (z.B. einen Sicherheitshinweis) an einer Stelle definieren und in vielen Dokumenten wiederverwenden. Das spart Zeit und sorgt für Konsistenz.
- Flexibel: Die Textdateien können in verschiedene Formate (HTML, PDF, EPUB) exportiert werden.
Nachteile:
- Lernkurve: Der Einstieg ist etwas anspruchsvoller als bei Markdown, da die Syntax komplexer ist.
- Kein WYSIWYG: Ihr seht nicht direkt, wie das Endergebnis aussieht, sondern müsst das Dokument erst kompilieren.

Auch für AsciiDoc gibt es diverse Hilfsmittel / Tools über alle Platformen verteilt: Linux, Mac und Windows Nutzer können alle auf Asciidoctor, SciTE oder AsciiDocFX zurückgreifen, das AwesomeAsciiDoc Github Projekt listet aber auch Plugins, Tools und alles andere was das Herz begehrt.

3. DITA & das DITA Open Toolkit

Was ist das? DITA (Darwin Information Typing Architecture) ist ein XML-basierter Standard zur Erstellung und Veröffentlichung von technischer Dokumentation. Es ist ein strukturierter Ansatz, der auf der Idee von Topics (kleine, wiederverwendbare Informationseinheiten) basiert. Diese Topics werden in einer DITA Map organisiert, die die Struktur eurer Dokumentation definiert. Das DITA Open Toolkit (DITA-OT) ist das Herzstück des Systems – ein Open-Source-Publishing-Engine, das DITA-Dateien in verschiedene Ausgabeformate wie PDF, HTML, und mehr umwandelt. Tools wie der oXygen XML Editor bieten eine intuitive Oberfläche, um DITA-Dateien zu erstellen und das DITA-OT zu nutzen.
Vorteile:
- Maximale Wiederverwendbarkeit: Einmal geschriebene Topics können in unzähligen Dokumenten wiederverwendet werden. Das ist ideal für Produktlinien oder Dokumente mit vielen ähnlichen Abschnitten.
- Konsistenz und Standardisierung: Durch die strikte Struktur wird die Qualität und Einheitlichkeit der Dokumentation sichergestellt.
- Separation von Inhalt und Format: Ihr konzentriert euch nur auf den Inhalt. Das Layout wird später durch das DITA-OT festgelegt. So könnt ihr ein Dokument mit einem Klick für die Online-Hilfe oder als PDF-Handbuch generieren.
Nachteile:
- Hohe Komplexität und Lernkurve: Der Einstieg in DITA und XML erfordert Zeit und spezielle Schulungen. Es ist definitiv nichts für ein schnelles Projekt.
- Hohe Kosten: Die professionellen XML-Editoren, die für eine effiziente Arbeit mit DITA quasi unerlässlich sind, sind meist kostenpflichtig.

Als kostenpflichtige Beispiel nenne ich hier mal Framemaker von Adobe oder oXygen, auf der OpenSource/Freeware Seite fällt mir Codex ein. Durch den offenen XML Standard und das Toolkit kann aber auch jeder selbst mit OpenJDK wie Amazon Corretto oder Azul Zulu seine eigenen Unterbau basteln.

4. Document360

Was ist das? Document360 ist eine moderne, cloudbasierte Wissensdatenbank-Plattform, die speziell für die Erstellung von Online-Hilfe, Self-Service-Portalen und internen Wissensdatenbanken entwickelt wurde.
Vorteile:
- All-in-One-Lösung: Von der Erstellung über die Veröffentlichung bis hin zur Analyse des Nutzerverhaltens ist alles in einem Tool vereint.
- Einfache Bedienung: Die Benutzeroberfläche ist intuitiv und auch für Nicht-Techniker leicht zu bedienen. Der Editor unterstützt Markdown, was einen schnellen Einstieg ermöglicht.
- Analyse-Tools: Ihr könnt sehen, welche Artikel gelesen werden, welche Suchbegriffe die Nutzer verwenden und wo es Wissenslücken gibt. Das hilft euch, eure Dokumentation kontinuierlich zu verbessern.
Nachteile:
- Kosten: Als SaaS-Lösung (Software-as-a-Service) fallen monatliche oder jährliche Gebühren an, die je nach Teamgröße variieren.
- Abhängigkeit: Ihr seid an die Plattform gebunden und könnt die Inhalte nicht einfach in einem anderen Tool weiterverarbeiten.

Dies ist eine eigenständige, ClosedSource Platform, mit allen entsprechenden Vor und Nachteilen. Schnittstellen zu quasi allen Helpdesk und Collaboration-Tools sind aber vorhanden, Einbindung in bestehenden Techstack somit keine große Hürde.

5. Adobe RoboHelp

Was ist das? RoboHelp ist ein klassisches und sehr etabliertes Help Authoring Tool (HAT) von Adobe. Es ist ein Desktop-Tool, das die Erstellung von Online-Hilfe, Wissensdatenbanken und vielem mehr ermöglicht.
Vorteile:
- Umfangreiche Funktionen: RoboHelp bietet alles, was das Technical Writer-Herz begehrt: von der Wiederverwendung von Inhalten über die Verwaltung von Variablen bis hin zu komplexen Layouts.
- Integration: Es lässt sich gut mit anderen Adobe-Produkten und externen Systemen integrieren.
- Stabile Basis: Als langlebiges Produkt hat es eine große Community und ist sehr ausgereift.
Nachteile:
- Komplexität: Aufgrund der vielen Funktionen kann der Einstieg überwältigend sein.
- Kosten: Auch RoboHelp ist ein kostenpflichtiges Tool, das eine Investition darstellt.

Der Opa unter den Tools, Adobe Robohelp ist eigentlich in dieser Aufzählung nicht ganz richtig untergebracht. Dennoch und gerade weil er extrem umfangreich und durch das Alter auch Vorreiter vieler anderer Tools ist, sollte er nicht unerwähnt bleiben.

Anleitungen und Prozesse: Euer Wegweiser

Eine gute Wissensdatenbank enthält nicht nur statische Informationen, sondern auch dynamische Anleitungen und Prozesse. Das können zum Beispiel sein:

Onboarding-Anleitungen: Wie führt ihr neue Teammitglieder in die Arbeit ein?
Styleguides: Welche Regeln gelten für die Sprache, Formatierung und Terminologie in euren Dokumenten?
Workflows: Wie läuft der Prozess von der Recherche bis zur Veröffentlichung eines Dokuments ab?

Solche Anleitungen helfen nicht nur euch, sondern auch anderen Teams. Das Support-Team kann sich schnell einarbeiten, die Entwickler können nachschauen, wie sie Feedback geben und selbst neue Kollegen finden sich viel schneller zurecht. Das macht eure Arbeit transparenter und euer Team agiler.

Die Hintergründe als Technical Writer

Als Technical Writer seid ihr die Vermittler zwischen den Experten und den Nutzern. Ihr habt die einzigartige Fähigkeit, komplexe Sachverhalte so zu erklären, dass sie für jeden verständlich sind. Eine Wissensdatenbank ist dabei euer stärkster Verbündeter, denn sie hilft euch, diese Vermittlerrolle perfekt auszufüllen.

Indem ihr das Wissen im Unternehmen sammelt, seht ihr, wo Lücken sind und wo ihr ansetzen müsst. Ihr erkennt die Schmerzpunkte der Nutzer und könnt sie gezielt in eurer Dokumentation ansprechen. Eine gut gepflegte Wissensdatenbank ist also nicht nur ein Speicher für Informationen, sondern auch ein Spiegel eurer eigenen Expertise und eures Wertes für das Unternehmen. Sie zeigt, dass ihr nicht nur schreibt, sondern das gesamte Wissen des Unternehmens strukturiert und zugänglich macht.

Fazit: Nicht nur ein Werkzeug, sondern eine Superkraft

Eine Wissensdatenbank ist weit mehr als nur ein Tool. Sie ist eine strategische Entscheidung, die euch als Technical Writer und euer gesamtes Team effizienter, transparenter und besser macht. Indem ihr das Wissen zentralisiert, könnt ihr euch auf das konzentrieren, was ihr am besten könnt: komplexe Themen einfach und klar zu kommunizieren.

TL:DR

Fangt an, euer Wissen zu sammeln und zu strukturieren. Es lohnt sich!