Im Bereich der Technischen Dokumentation ist ein Redaktionsleitfaden (RLF) ein wichtiges Nachschlagewerk. Im Grunde genommen ist dieser „Styleguide“ eine Anleitung vom Technischen Redakteur für den Technischen Redakteur und enthält alle wesentlichen Informationen zur strukturierten Erstellung von Informationsprodukten.

Wenn der RLF gut strukturiert ist, kann er beliebig umfassend oder auch in mehrere Unter-Redaktionsleitfäden aufgeteilt sein. Dies ist dann hilfreich, wenn Aufbau und Inhalt mehrerer Dokumentarten getrennt voneinander beleuchtet werden sollen oder Leitfäden für diverse Endkunden zu erstellen sind.

Der RLF hat zum Ziel, Standards in der Informationsentwicklung zu dokumentieren. Diese können die Kapitelstruktur, das Layout, den Einsatz von Tabellen und Grafiken, den Inhalt selbst und die Sprache betreffen. Arbeitsprozesse werden darin festgehalten und einheitliche Qualitätskriterien geschaffen. Für neue Mitarbeiter dient er als Einarbeitungshandbuch.

Ein Redaktionsleitfaden ist, und da will ich niemandem etwas vormachen, zunächst keine besonders spannende Lektüre. Im Gegenteil, es ist eine Pflichtlektüre, die auch noch gepflegt und aktuell gehalten werden muss. Es spricht also rein gar nicht dagegen, diesem an sich spießigem Regelwerk etwas mehr Pepp und Dynamik zu verleihen. Wie das gelingen kann, ohne übertrieben und fachfremd zu wirken, erläutere ich in den nächsten Kapiteln.

Tools, die geeignet sind, um einen RLF zu schreiben

  • Der Klassiker Microsoft Word.
  • Adobe FrameMaker oder eine andere Publishing-Software.
  • Ein Redaktionssystem.
  • Ein Unternehmenswiki.

Es spricht wirklich nichts dagegen, einen Redaktionsleitfaden in Word, FrameMaker oder dem Redaktionssystem zu erstellen. Erst recht nicht, wenn dies ohnehin die primären Tools für die Dokumentationserstellung sind. Nicht geeignet sind meiner Meinung nach Microsoft Excel oder andere Tabellentools.

Der Charme eines Unternehmenswikis besteht hingegen darin, Wissen allen Mitarbeitern zugänglich zu machen, es zu verteilen und die Mitwirkung an Inhalten zu ermöglichen (ja, auch ein Redaktionsleitfaden kann für andere Abteilungen interessant sein und zu einer verlässlichen Informationsquelle werden!). Die Motivation, mit einem Wiki zu arbeiten, ist meistens groß, da dieses Tool einen Kontrast zu gewohnten (entweder sehr einfachen oder sehr komplexen) Systemen aufweist.

Im Fokus heute: Die Wiki-Software Confluence von Atlassian. Und die möchte ich nun näher beleuchten (ohne dafür Werbung machen zu wollen). Wir nutzen Confluence nicht nur zur Erstellung von Redaktionsleitfäden, sondern auch als Dokumentationstool und Knowledge-Base.

Confluence als Dokumentations-Werkzeug

Standardmäßig kommen diese Vorzüge von Confluence bei der Erstellung eines Redaktionsleitfadens zum Einsatz:

  • Versionierung und Versionskontrolle (damit sind Inhalte auf frühere Zustände rückversetzbar und werden vergleichbar),
  • Benachrichtigungsfunktion bei Änderungen an Seite oder Erwähnung als Person,
  • Kommentarfunktion (am Seitenende oder Inline),
  • Dateien hochladen (Abbildungen, Tabellen, Präsentationen, Dokumente etc.),
  • Seiten veröffentlichen (und damit allen zugänglich machen, die sie bisher nicht entdeckt haben),
  • Verlinkungen auf andere Seiten setzen,
  • anderen Teammitgliedern Aufgaben zuweisen,
  • Prozesse modellieren mit den integrierten BPMN-Tools.

Confluence ist übrigens auch als mobile App verfügbar. Die habe ich tatsächlich schon oft von unterwegs genutzt 😉.

8 tolle Confluence-Funktionen für die Erstellung eines RLF

Kurz vorab: Für Confluence gibt es Cloud-Abonnements, Serverlizenzen oder auch DataCenter-Lizenzen. Abhängig davon, was Sie erworben haben und ob Standard-Version oder Premium, stehen Ihnen unterschiedliche Funktionalitäten zur Verfügung. Apps und Makros lassen sich jedoch problemlos auch noch nachträglich kostenlos integrieren oder zukaufen (mit Administratorrechten).

Eingangs habe ich bereits erwähnt, dass man triste Redaktionsleitfäden auch spannender gestalten könnte. Was ich dafür tue?

Funktion #1 | Coole Emojis/Emoticons verwenden 

Ich baue Emojis/Emoticons ein. Damit sind nicht nur die gelben Gesichter gemeint, sondern auch andere „Cliparts“ wie ein Geldschein, Werkzeug, Handy, Ordner, Kalender, Häkchen, Kreuz, eine Glühbirne, Uhr uvw. Wir alle kennen diese Icons von unserer Lieblings-Nachrichtenapp – warum sollten wir sie nicht auch im Beruf nutzen?
Grundsätzlich lassen sich Emojis vor jede große Kapitelüberschrift setzen. Dort sprechen sie die Leser|innen am besten an.

Page-Layout-Makro

Emojis/Emoticons in Confluence

Funktion #2 | Abwechslung durch ein anderes Page Layout schaffen

Ich verwende ein besonderes Page Layout. Mit Platz für Marginalien, Eyecatcher, Infoboxen, Grafiken etc. So vermeiden Sie zähen Fließtext und machen den Inhalt für Interessierte schneller überschaubar. Sie können die Kapitel auch unterschiedlich gestalten, aber stellen Sie sicher, dass sich die Leser|innen jederzeit schnell zurechtfinden.

Page-Layout-MakroPage-Layout-Makro

Funktion #3 | Mit horizontalen Linien für Ordnung sorgen

Ich nutze horizontale Linien als optisches Trennmittel. Entweder zwischen Kapiteln oder auch innerhalb von Kapiteln. Entscheiden Sie sich pro Redaktionsleitfaden für eine Funktion.

Horizontale-Linie-Makro Horizontale-Linie-Makro

Funktion #4 | Farbige Panels als Eyecatcher setzen

Ich nutze verschiedenfarbige Panels, um damit z.B. ein besonderes Augenmerk auf Spezialthemen zu legen und aus den ansonsten so erstarrten Strukturen eines RLF auszubrechen.

Panel-Makro Panel-Makro

Funktion #5 | Entscheidungsfindungen optisch hervorheben

Ich nutze das Makro Decision, um besondere Entscheidungsfindungen festzuhalten, die eine Änderung in der Dokumentation zur Folge haben. Diese Entscheidungen können in der Technischen Redaktion festgelegt oder aber auch von außerhalb herangetragen worden sein (Gesamtabteilung, Unternehmen, Endkunde, Anwender etc.).

Decision-Makro Decision-Makro

Mit dem Makro Decision report können Sie sich übrigens alle Entscheidungen zusammenfassend anzeigen lassen.

Funktion #6 | Datumsangaben als Makro pflegen

Ich halte solche Entscheidungsfindungen außerdem gerne in Kombination mit dem Makro Datum fest. Das sticht deutlich besser aus dem Fließtext hervor als ein Datum im Absatzformat.

Datumsangaben Datumsangaben

Funktion #7 | Statusinformationen schnell ablesbar gestalten

Natürlich sollte der Redaktionsleitfaden immer aktuell gehalten werden. Ich nutze jedoch bewusst das Wörtchen sollte. Denn: Immer dann, wenn viele Dokumentarten gleichzeitig entstehen, neue Prozesse entwickelt werden oder viele Endkunden zu bedienen sind, kommt es immer wieder vor, dass die Aktualisierung des Redaktionsleitfadens verspätet erfolgt. Kleiner Tipp: Ich nehme mir vor, den oder die RLF einmal im Monat zu aktualisieren. Damit das dann schnell geht, arbeite ich gerne mit Statusinformationen (Makro Status).

Statusinformationen Statusinformationen

Funktion #8 | Aktualisierungen/Änderungen deutlich kennzeichnen

In typischen Word-Redaktionsleitfäden befindet sich die Änderungshistorie meist am Ende des Dokuments. Oft liest sie dann niemand oder Aktualisierungen am RLF werden gar nicht erst festgehalten. Confluence sorgt durch die standardmäßige (jedoch sehr unübersichtliche) Änderungs-Benachrichtigungsfunktion zwar schon für Abhilfe bei diesem Problem, aber ich hebe die letzten Änderungen dennoch gerne zuätzlich im RLF hervor und platziere sie bewusst weit vorne im Kapitelaufbau. Zusätzlich lässt sich die Change History mit einem farbigen Panel so in Szene setzen, dass jeder Leser die letzten Änderungen gleich erkennt.

 

Änderungshistorie Änderungshistorie

 

Confluence mit Jira und Trello optimal nutzen

Es gibt viele Gründe, Confluence gemeinsam mit den beiden beliebten Geschwister-Anwendungen Jira und Trello zu nutzen. Speziell bei der Erstellung von Informationsprodukten im Bereich Softwareentwicklung, wenn es darum geht, Sprints zu koordinieren oder Anforderungen zu analysieren, bieten die Tools zahlreiche Kopplungsmodi und verhalten sich komplementär.
Vorteile der gemeinsamen Nutzung, die speziell bei der Erstellung des Redaktionsleitfadens interessant sein können:

Confluence & Jira

Jira-Tickets auf einer Confluence-Seite abbilden

Jira-Tickets in Confluence-Seite integrieren

Jira-Tickets in Confluence-Seite integrieren

Wie das geht? Das Jira-Ticket über das Makro Insert Jira Issue/Filter einfügen ODER die URL des Jira-Tickets an die gewünschte Stelle der Confluence-Seite einkopieren.

Effekt: Das Ticket wird direkt als Link angezeigt. Außerdem wird nach Verlassen des Edit-Modus oberhalb der Seitenüberschrift automatisch ein Drop-Down-Menü eingerichtet, das die Anzahl und Details zu Verlinkungen nach Jira anzeigt.

Aufgaben aus Confluence heraus in Jira als neues Ticket anlegen

Jira-Tickets aus Confluence heraus anlegen (1) Jira-Tickets aus Confluence heraus anlegen (1)

 

Jira-Tickets aus Confluence heraus anlegen (2) Jira-Tickets aus Confluence heraus anlegen (2)

Wie das geht? Im Lese-Modus ist dies durch Markieren eines Wortes oder Satzes möglich ((1) und (2)). Im Edit-Modus hingegen ist dies über das Makro Insert Jira Issue/Filter möglich.

Effekt: Jira-Tickets können on-the-fly angelegt werden, ohne dass die Jira-Anwendung geöffnet sein muss.

Im Jira-Ticket einen Link zu einer Confluence-Seite hinterlegen

Confluence-Link in Jira-Ticket einfügen Confluence-Link in Jira-Ticket einfügen

Wie das geht? Dazu wird das Ticket in Jira geöffnet und im Dialogfenster Link der entsprechende Link eingetragen (wo genau der Befehl „Link“ zu finden ist, unterscheidet sich je nach Lizenztyp).

Effekt: Wenn in Jira die Dokumentation zu kurz ausfällt, kann auf umfassendere Informationen in Confluence verwiesen werden.

Confluence & Trello

In einer Trello-Karte einen Link zu einer Confluence-Seite hinterlegen & aus einer Trello-Karte heraus eine neue Seite in Confluence erstellen

Confluence-Link in Trello-Karte einfügen (1) | Confluence-Seite aus Trello heraus erstellen (2) Confluence-Link in Trello-Karte einfügen (1) | Confluence-Seite aus Trello heraus erstellen (2)

Wie das geht? Einfach aus einer beliebigen Trello-Karte heraus das Power-up „Confluence Cloud“ hinzufügen. Dann kann es schon losgehen.

Effekt: Mit dem Verweis auf eine Confluence-Seite wird die Trello-Karte mit umfassendem Inhalt angereichert; durch das „spontane“ Erstellen einer neuen Seite aus Trello heraus lässt sich ein Dokumentationsgedanke schnell und einfach in Confluence erfassen.

Jira & Trello

In einer Trello-Karte einen Link zu einem Jira-Ticket hinterlegen & aus einer Trello-Karte heraus ein neues Jira-Ticket erstellen

Jira-Link in Trello-Karte einfügen (1) | Jira-Ticket in Trello erstellen (2) Jira-Link in Trello-Karte einfügen (1) | Jira-Ticket in Trello erstellen (2)

Wie das geht? Einfach aus einer beliebigen Trello-Karte heraus, das Power-up „Confluence Cloud“ hinzufügen. Dann kann es schon losgehen.

Effekt: Für diejenigen Mitarbeiter, die selbst nicht in Jira arbeiten, aber über den Status, die Priorität und die Inhalte von Tickets informiert sein wollen, ist das Einfügen eines Jira-Links eine gute und einfache Art des Wissens- und Informationstransfers. Hingegen ist das Erstellen eines Jira-Tickets direkt aus Trello heraus immer dann denkbar und sinnvoll, wenn anderen Mitarbeitern Aufgaben nach Jira zugewiesen werden sollen.

Fazit

Grundsätzlich lässt sich ein Redaktionsleitfaden sehr gut mit Confluence erstellen. Das Tool ist intuitiv zu bedienen, kann kollaborativ genutzt werden und bietet alle wesentlichen Funktionalitäten, die es dazu braucht. Wer seinen RLF nicht bereits in einem Redaktionssystem schreibt, der ist mit Confluence meiner Meinung nach besser bedient als mit Word und Co.

Viel Erfolg beim Testen!


Übrigens: In unserem STYRZ-Newsletter halten wir Sie zu diversen Themen rund um die Technische Redaktion auf dem Laufenden. Jetzt anmelden!