Skip to end of metadata
Go to start of metadata

Confluence Cloud Dokumentation

Confluence für die technische Dokumentation verwenden

Confluence ist eine flexible Plattform mit einer Reihe von Funktionen und Add-ons, die dir bei der Erfassung, Verteilung und Aktualisierung deiner technischen Dokumentation helfen können. Im Folgenden findest du einige Tipps, die dir bei der Einrichtung deiner Website für technische Dokumentation helfen und dir Zeit und Mühe bei der Verwaltung des Lebenszyklus deiner Dokumentation ersparen.


Erstelle deinen Bereich für die Dokumentation

So beginnst du mit deiner Dokumentation

  1. Wähle in der Confluence-Navigation Bereiche aus, wähle Alle Bereiche anzeigen aus und klicke auf Bereich erstellen.
  2. Wähle Dokumentationsbereich (du erhältst eine benutzerdefinierte Übersicht mit einem Suchfeld - dem Livesearch-Makro - um nur deinen Dokumentationsbereich zu durchsuchen, ein kürzlich aktualisiertes Makro und ein paar andere Goodies) und klicke auf Weiter.
  3. Gib deinem Bereich einen Namen und klicke auf Erstellen.

Confluence erstellt automatisch den Schlüssel für den Bereich und die Übersicht des Bereichs. Du kannst die Übersicht jederzeit anpassen - wie sie aussieht, ist ganz deine Entscheidung!

Zeit sparen durch Wiederverwendung von Inhalten

Wenn du etwas in deinem Dokumentationsbereich mehrfach verwenden willst - sei es ein Wort, ein Satz oder ein Absatz, ein Bild, eine Produktversionsnummer oder etwas anderes - kannst du es einmal erstellen und auf so vielen Seiten wie du willst einfügen (oder in der Kopf- und/oder Fußzeile verwenden). Die Einbindung erspart es dir nicht nur, dass du dasselbe mehrmals tippst, sie macht es auch einfacher, wenn sich Dinge ändern - es ist viel besser, die Informationen an einer Stelle zu aktualisieren als z.B. an 47!

Es gibt 3 Makros, mit denen du Inhalte wiederverwenden kannst:

  • Das Makro Auszug (Excerpt), um einen wiederverwendbaren Abschnitt oder Auszug auf einer Seite zu definieren - füge Inhalte in dieses Makro ein und du kannst sie auf so vielen Seiten wie du willst wiederverwenden.
  • Das Makro Auszug einschließen (excerpt-include), um den Inhalt eines Auszugs auf einer anderen Seite einzuschließen.
  • Das Makro Seite einschließen (include), um den gesamten Inhalt einer Seite auf einer anderen Seite einzuschließen.

Nehmen wir an, du erstellst für jede Hauptversion deines Produkts Versionshinweise und möchtest die Intro jeder Versionshinweis-Seite auf einer "Was ist neu"-Seite einfügen. Platziere jede Intro der Versionshinweise in einem Auszugs Makro und füge dann ein Auszug Einschließen Makro für jeden Satz von Versionshinweisen zur "Was ist neu"-Seite hinzu. Deine Intro erscheint wie von Zauberhand auf der Seite mit den Neuigkeiten, und wenn du die Versionshinweise aktualisierst, wird auch die Seite mit den Neuigkeiten automatisch aktualisiert.

  1. Auszüge: Die Einleitungen zu diesen Seiten sind in Auszugs Makros. 
  2. Auszug einschließen: Dies sind Auszug-Einschluss-Makros. 

Ein weiteres Beispiel ist eine der Möglichkeiten, wie wir das Makro Seite einschließen verwenden. Immer wenn die Ellipse in unserer Dokumentation auftaucht - z. B. unter -> Kopieren - handelt es sich um ein Makro zum Einfügen von Seiten. Wir haben eine Seite mit genau diesem Bild und können es immer dann einfügen, wenn wir eine Ellipse brauchen.

Warum verwenden wir ein Seite einschließen Makro für ein kleines Bild? Nur für den Fall, dass dieses UI-Element jemals geändert wird. Wenn wir das Bild an jede Seite anhängen, gibt es vielleicht 50 Seiten, die wir aktualisieren müssen, wenn sich etwas ändert; wenn wir ein Seite einschließen Makro verwenden, aktualisieren wir es einmal und es wird überall geändert. Auf diese Weise können wir auch feststellen, auf wie vielen Seiten wir das Bild verwenden. Unter > Erweiterte Information > Seiteninformationen können wir sehen, wie viele eingehende Links auf diese Seite verweisen, und das sagt uns, wie viele Seiten das Bild verwenden.

Erstellen einer Bibliothek (optional)


Du kannst Inhalte von jeder Confluence Seite einbinden, aber vielleicht möchtest du eine Bibliothek erstellen, um Inhalte zu speichern, die speziell für die Wiederverwendung bestimmt sind. Die Bibliothek ist keine spezielle Funktion von Confluence; die Seiten in der Bibliothek sind genau wie jede andere Confluence Seite. Dies ist nur eine Technik, die du anwenden kannst, wenn du Inhalte speichern willst, die speziell für die Wiederverwendung bestimmt sind.

So erstellst du deine Inklusions-Bibliothek:

  1. Klicke auf Erstellen und erstelle eine neue Seite in deinem Bereich. 
  2. Gib einen passenden Titel ein. Wir verwenden "_ConfluenceInclusions" (der Unterstrich vor dem Titel zeigt, dass diese Seite etwas Besonderes ist). 
  3. Gib einige Inhalte ein und veröffentliche die Seite. Wir geben einen Text ein, der den Zweck der Bibliothek erklärt und wie man den Inhalt wiederverwendet. 
  4. Wähle in der Seitenleiste die Bereichseinstellungen aus.
  5. Wähle Neu sortieren aus dem Tab Seiten verwalten
  6. Wähle die eckige Klammer -> aus, um den Verzeichnisbaum der Seite zu erweitern.
  7. Ziehe deine neue Seite über die Übersicht des Bereichs. 
  8. Gehe zu deiner neuen Seite mit den Einschlüssen und wähle Erstellen, um untergeordnete Seiten mit deinen wiederverwendbaren Inhalten hinzuzufügen.
  9. Ort der Bibliothek: Ziehe deine Bibliothek über den Rest deiner Dokumentation.

Da du die Seiten in die "Wurzel" des Bereichs verschoben hast, werden sie nicht bei den Seiten deines Bereichs angezeigt. Die Seiten werden jedoch bei anderen Suchen gefunden, da es sich um normale Confluence Seiten handelt. 

Seitenvorlagen verwenden

Eine oder mehrere Seitenvorlagen zu erstellen, kann eine echte Zeitersparnis sein, wenn du viele Seiten mit demselben Layout erstellst. Wenn du ständig dieselben Makros wie Tafeln und Inhaltsverzeichnisse hinzufügst, kannst du sie in eine Vorlage packen - du kannst mit einer anfangen, aber so viele erstellen, wie du brauchst, um deine Effizienz zu steigern.

So erstellst du eine Seitenvorlage, die in allen Bereichen verfügbar ist:

  1. Gehe zu (Einstellungen) in der Confluence-Navigation.
  2. Wähle Globale Vorlagen und Blueprints aus der Liste auf der linken Seite aus.
  3. Wähle die Schaltfläche Globale Seitenvorlage hinzufügen oben rechts aus.
  4. Erstelle deine Vorlagenseite und wähle Speichern aus.

Ausführliche Informationen zu Seitenvorlagen findest du unter Blueprints und benutzerdefinierte Vorlagen.                                                                                                                                                                                                          

Um schnell zu Globale Vorlagen und Blueprints oder einer anderen Verwaltungsseite zu gelangen, drückst du auf / und gibst den Namen der gesuchten Verwaltungsseite ein.

Entwerfe deine Arbeit

Wenn du eine neue Seite in deiner Dokumentation erstellst, möchtest du sie wahrscheinlich nach und nach abspeichern und sie von einigen wenigen Personen überprüfen lassen, um ihnen Feedback zu geben. Eine grobe Beschreibung dieses Arbeitsablaufs ist "Entwurf, Überprüfung, Veröffentlichung".

Du möchtest nicht, dass dein Team halbfertige Seiten zu sehen bekommt und die meisten Dokumentationen müssen überprüft werden, bevor sie fertiggestellt werden:

  1. Erstelle eine Seite und schränke ihre Berechtigungen ein. Du könntest zum Beispiel die Ansicht auf eine Gruppe von Personen beschränken, wie dein Team oder ein paar ausgewählte Personen. Auf einer öffentlichen Seite könntest du die Ansicht auf Mitarbeiter/innen beschränken, damit die Allgemeinheit die Seite nicht sehen kann.
  2. Schreibe den Inhalt deiner Seite. 
  3. Teile die Seite mit deinen Reviewern und bitte sie um Feedback. (Achte darauf, dass du sie nicht daran hinderst, die Seite zu sehen!) Die Prüfer/innen können unten auf der Seite Kommentare hinzufügen oder den Text markieren, um einen Inline-Kommentar hinzuzufügen. Wenn du ihnen die Erlaubnis gibst, können sie den Inhalt der Seite auch direkt bearbeiten.
  4. Veröffentliche die Seite, wenn sie fertig ist, indem du Folgendes tust:
    1. Lösche alle Kommentare auf der Seite. 
    2. Entferne die Einschränkungen für die Seite, damit andere sie sehen können. 

Du hast deine Seite jetzt veröffentlicht. Die Berechtigungen für den Bereich und die Seite bestimmen nun, wer die Seite sehen und/oder aktualisieren kann.


Links und Anker verwenden

Links hinzufügen


Auf jeder Dokumentationsseite ist es wichtig, dass du von einer Seite zur anderen verlinken kannst, und oft auch zu bestimmten Abschnitten auf einer Seite. Du kannst einer Confluence Seite eine beliebige URL hinzufügen, die von Confluence automatisch erkannt und in einen Link umgewandelt wird.

Wenn du die URL einer anderen Seite in deine Confluence Seite einfügst, zeigt Confluence den Linktext als Seitennamen an und verwandelt ihn in einen relativen Link, d.h. wenn sich der Name der Seite ändert, passt Confluence den Link an, damit er nicht unterbrochen wird.

Hinzufügen und Verlinken von Ankern


Im Legacy Editor kannst du mit dem Anker-Makro Verweise in deiner Dokumentation erstellen, die von überall aus verlinkt werden können. Ich habe einen Anker am Anfang dieser Seite eingefügt, damit du mit einem Klick zum Anfang zurückkehren kannst.  Dieses Makro ist im neuen Editor nicht verfügbar.

In unserer Dokumentation zu Links und Ankern findest du alle Details dazu, wie du im alten und im neuen Editor auf Inhalte verlinken kannst.

Nützliche Makros

Confluence wird mit einer Vielzahl von Makros ausgeliefert, und es gibt einige, die für die technische Dokumentation besonders nützlich sind. Hier sind ein paar Beispiele:

Inhaltsverzeichnis Makro


Das Makro für das Inhaltsverzeichnis hilft bei der Navigation auf langen Seiten, indem es die Struktur des Inhalts zusammenfasst und Links zu den Überschriften auf der Seite bereitstellt. Das Beste daran ist, dass du nichts weiter tun musst, als das Makro hinzuzufügen. Sobald du es hinzugefügt hast, erkennt es automatisch Überschriften und fügt sie dem Inhaltsverzeichnis hinzu.

Tipp-, Hinweis-, Info-, Warn- und Panel-Makros


Bei der Erstellung von Dokumentationen gibt es oft Elemente auf einer Seite, die du hervorheben oder auf die du die Aufmerksamkeit der Betrachter lenken möchtest. Confluence wird mit den Makros Tipp, Info, Warnung, Hinweis und Panel ausgeliefert, mit denen du die Aufmerksamkeit des Betrachters auf einen bestimmten Teil deines Inhalts lenken kannst.

Diese einzelnen Makros sind ein Teil des Legacy-Editors, aber im neuen Editor wurden sie zu einem Info-Panel-Element zusammengefasst.

Behalte den Überblick über Seitenaktualisierungen

In Confluence ist es durchaus üblich, dass mehrere Personen eine Seite aktualisieren. Technische Redakteure müssen wissen, was mit unseren Dokumenten passiert, sowohl während der Überprüfung als auch nach der Veröffentlichung.

Seiten oder den Bereich beobachten


Damit du weißt, wann Änderungen vorgenommen werden, empfiehlt es sich, Seiten oder sogar den gesamten Bereich zu beobachten. Wenn auf den Seiten, die du beobachtest, Änderungen vorgenommen werden oder jemand sie kommentiert, erhältst du eine E-Mail-Benachrichtigung, die dich darüber informiert, wer was geändert hat.

Wenn du dich auf einer Seite in deinem Dokumentationsbereich befindest, wähle die Schaltfläche Beobachten oben rechts auf der Seite. Von dort aus kannst du wählen, ob du nur diese Seite oder alle Seiten in diesem Bereich beobachten möchtest.

Seitenverlauf anzeigen


Confluence erstellt jedes Mal eine neue Version der Seite, wenn jemand die Seite bearbeitet. Der Seitenverlauf zeigt alle Versionen mit Datum, Autor und Kommentaren zur Aktualisierung an.

Um den Seitenverlauf einzusehen, gehst du auf die Seite und wählst -> Seitenverlauf

In der Ansicht des Seitenverlaufs kannst du:

  • den Inhalt einer bestimmten Version der Seite anzeigen.
  • zu einer bestimmten Version zurückkehren (wiederherstellen).
  • zwei beliebige Versionen zum Vergleich auswählen, um zu sehen, was sich zwischen diesen beiden Versionen geändert hat.

Liste der Mitwirkenden anzeigen


Wenn du auf einen Blick sehen willst, wer eine Seite oder mehrere Seiten aktualisiert hat, kannst du das Makro Beitragende hinzufügen. Dieses Makro zeigt eine anpassbare Liste der Personen an, die einen Beitrag zur Seite geleistet haben, indem sie sie erstellt, bearbeitet oder, optional, kommentiert haben.

Anpassen des PDF-Exports

Wenn du planst, eine PDF-Version deiner Dokumentation bereitzustellen - sei es für E-Mail, Download, Druck oder eine andere Form der Veröffentlichung - kannst du das Aussehen der PDF-Datei anpassen, indem du eine Titelseite, eine Kopf- und eine Fußzeile hinzufügst.

Wie du dabei vorgehst, hängt davon ab, ob du den PDF-Export für einen bestimmten Bereich oder für deine gesamte Website anpassen möchtest. Wenn du diese Änderungen vornehmen möchtest, findest du auf unserer Seite PDF-Exporte anpassen genauere Anweisungen.

Andere nützliche Tools und Apps

Du kannst Confluence mit Apps erweitern, je nachdem, was du für deine Dokumentation und deinen Workflow brauchst. Hier sind einige nützliche Add-ons, die auf dem Atlassian Marketplace erhältlich sind - die meisten davon nutzen wir selbst - und mit denen du die Funktionen von Confluence erweitern kannst.

Bereich kopieren (unterstützt)


Die App "Copy Space" für Confluence macht genau das, was ihr Name sagt: Sie ermöglicht es einem Bereichsadministrator, einen Bereich zu kopieren, einschließlich der Seiten innerhalb des Bereichs. Das ist ideal, wenn du eine Vorlage für einen Bereich brauchst, die du kopieren kannst, um andere Bereiche zu erstellen.

Diese App ist auch nützlich, wenn du eine Kopie eines aktuellen Bereichs zu einem bestimmten Zeitpunkt archivieren musst, z. B. wenn du von einer Version deines Produkts zur nächsten wechselst - kopiere den Bereich, gib ihm einen neuen Namen und behalte ihn, wo immer du willst, ohne dass der bestehende Bereich verloren geht.

Die App "Copy Space" kopiert derzeit keine Seitenverläufe, Blogeinträge und E-Mails.

draw.io Diagrams and Whiteboards (unterstützt)

Erstelle leistungsstarke, einfach zu bedienende und sichere Diagramme und Whiteboards mit draw.io. Die bestbewertete Confluence-Diagrammlösung seit 2013.


Gefällt dir, was du siehst? Teste Confluence für deine technische Dokumentation.



Zurück zum Hauptmenü   Nächstes Thema  







Confluence

Diese Seite wurde zuletzt am 04.08.2022 geändert.