Ein Diagramm, viele Seiten: Wie referenzierte Diagramme Ihre Confluence-Dokumente synchron halten
Es gibt eine bestimmte Art von Dokumentationsschulden, die sich über Monate still ansammelt, bis man sie nicht mehr ignorieren kann. Ein Diagramm wird für eine Designspezifikation erstellt. Jemand kopiert es ins Runbook. Ein drittes Team bettet eine Version in den Onboarding-Leitfaden ein. Plötzlich zeigen drei Seiten in Ihrem Confluence-Bereich drei verschiedene Versionen.

Es gibt eine bestimmte Art von Dokumentationsschulden, die sich über Monate still ansammelt, bis man sie nicht mehr ignorieren kann. Ein Architekturdiagramm wird für eine Designspezifikation erstellt. Jemand kopiert es ins Runbook. Ein drittes Team bettet eine Version in den Onboarding-Leitfaden ein. Mit der Zeit entwickelt sich das System weiter (ein neuer Dienst kommt hinzu, eine Abhängigkeit fällt weg, eine Namenskonvention ändert sich) – und plötzlich zeigen drei Seiten in Ihrem Confluence-Bereich drei verschiedene Versionen dessen, was eigentlich dasselbe Diagramm sein sollte. Niemand weiß genau, welches aktuell ist. Niemand will alle drei aktualisieren. Die Dokumentation wird unzuverlässig – gerade weil sie gründlich sein wollte.
Das ist eines der häufigsten und zugleich unauffällig schädlichsten Probleme in der Teamdokumentation. Es entsteht, weil Diagramme als statische Inhalte statt als gemeinsame Referenzen behandelt werden. Capable Diagrams löst dieses Problem direkt mit dem Makro „Referenced Diagram“: Damit betten Sie ein einziges Diagramm auf beliebig vielen Confluence-Seiten ein, und jede Instanz zeigt automatisch die neueste Version des Originals.
Die Copy-and-paste-Falle
Der Impuls, ein Diagramm zu kopieren, ist verständlich. Wenn Sie ein Runbook schreiben und die aktuelle Systemtopologie einfügen müssen, ist es am schnellsten, das Diagramm von der Architekturseite zu nehmen und einzufügen. Das funktioniert sofort. Das Problem: Kopie und Original sind nun zwei unabhängige Objekte. Es gibt keine Verbindung zwischen ihnen, keinen Mechanismus, der eine Änderung am einen dem anderen mitteilt, und keine Warnung, wenn sie auseinanderlaufen.
Für kleine Teams mit einer Handvoll Dokumentationsseiten ist manuelles Synchronisieren lästig, aber machbar. Für größere Organisationen oder Teams, die im Tempo moderner Engineering- oder Produktabteilungen arbeiten, wird es unhaltbar. Ein Plattformteam, das gemeinsame Infrastruktur betreut, hat dasselbe Architekturdiagramm womöglich in einem Dutzend verschiedener Bereiche: Onboarding-Dokumente, Playbooks für die Reaktion auf Vorfälle, API-Referenzen, Seiten zur Quartalsplanung und mehr. All das manuell synchron zu halten, ist nicht nur mühsam – es ist ein eigener Job.
Die Kosten beschränken sich nicht auf den Pflegeaufwand. Es geht auch Vertrauen verloren. Stoßen Teammitglieder auf widersprüchliche Diagramme, zweifeln sie an der gesamten Dokumentation. Sie suchen nach der „echten“ Version, oft indem sie Kollegen fragen – und das untergräbt genau den Zweck schriftlicher Dokumentation.
So funktionieren referenzierte Diagramme
Das Makro „Referenced Diagram“ in Capable Diagrams kehrt das Copy-and-paste-Prinzip um. Statt Diagramminhalte auf eine neue Seite zu duplizieren, fügen Sie eine Referenz auf das Originaldiagramm ein. Das Makro verweist auf eine einzige verlässliche Quelle (das Diagramm auf seiner Ursprungsseite) und zeigt es überall dort an, wo Sie das Makro platzieren. Aktualisiert jemand das Original, zeigt jede referenzierende Seite sofort die neue Version. Es gibt keinen manuellen Synchronisierungsschritt, keinen Abgleich zwischen Kopien und kein Risiko, dass Versionen auseinanderdriften.
Damit ändert sich grundlegend, wie Sie über die Platzierung von Diagrammen in Confluence denken. Statt zu fragen „Wo soll dieses Diagramm liegen?“, lautet die Antwort nun: „Es liegt an einem Ort, und überall sonst wird darauf verwiesen.“ Die Ausgangsseite kann ein eigener Architekturbereich sein, die Seite mit den technischen Standards eines Teams oder ein maßgebliches Systemdesign-Dokument. Überall, wo das Diagramm erscheinen soll, erscheint es – doch Sie pflegen immer nur ein einziges Diagramm.
Ein Praxisbeispiel: Dokumentation im Platform Engineering
Nehmen wir ein Platform-Engineering-Team, das für eine gemeinsam genutzte Datenpipeline zuständig ist. Die Pipeline-Architektur ist auf einer zentralen Seite im Bereich des Teams dokumentiert. Dieses Diagramm ist maßgeblich: Es zeigt den aktuellen Stand von Produzenten, Konsumenten, Transformationsschichten und Datenspeichern.
Mit der Zeit muss dasselbe Diagramm an mehreren Stellen erscheinen: Der Onboarding-Leitfaden für neue Mitarbeitende nutzt es, um Engineers einen Überblick über das Gesamtsystem zu geben. Das Playbook für die Störungsbehebung hilft damit den Verantwortlichen, bei einem Ausfall die Auswirkungen einzuschätzen. Die Seite zum Quartalsbericht verlinkt darauf, um die Entwicklung der Infrastruktur zu belegen. Und eine Seite zur Data Governance markiert darin, welche Komponenten regulierte Daten verarbeiten.
Ohne referenzierte Diagramme enthält jede dieser Seiten eine statische Kopie. Wechselt das Team von einem Message Broker zum anderen, muss jemand daran denken, fünf einzelne Seiten zu aktualisieren. Eine wird unweigerlich vergessen. Das Playbook für die Störungsbehebung veraltet, ohne dass es jemand merkt – bis zu dem Moment, in dem es am meisten zählt.
Mit dem Referenced Diagram Macro aktualisiert das Team das Diagramm einmal auf der Quellseite. Alle fünf Seiten zeigen sofort die aktuelle Architektur. Der Onboarding-Leitfaden ist aktuell. Das Playbook stimmt. Die Governance-Seite bildet das echte System ab. Das Team konzentriert sich auf die Arbeit, nicht auf die Pflege.
Mehr als Architektur: weitere wertvolle Anwendungsfälle
Dieselbe Logik gilt für jedes Diagramm, das in mehreren Dokumentationen gebraucht wird. Prozessdiagramme, die sowohl im Team-Wiki als auch in einem Handbuch für Kunden stehen, profitieren von einer zentralen Steuerung. Organigramme auf den Einstiegsseiten von Abteilungen und in der HR-Dokumentation sollten immer dieselbe Struktur zeigen. Roadmap-Diagramme, die in Produkt-, Engineering- und Führungsbereichen geteilt werden, sollten nie auseinanderlaufen.
Besonders nützlich ist das Referenced Diagram Macro für Teams, die Dokumentation über mehrere Confluence-Bereiche hinweg verwalten. Mit einer einzigen referenzierten Quelle kann ein Plattformteam seine Infrastrukturdiagramme abhängigen Produktteams bereitstellen, ohne diesen Bearbeitungsrechte für die Quellseite zu geben. Das Diagramm wandert über Bereiche hinweg, die Verantwortung bleibt dort, wo sie hingehört.
Den größten Nutzen haben Teams, die lebendige Dokumentation pflegen – Wikis und Wissensdatenbanken, die laufend aktualisiert statt einmal veröffentlicht werden. Jedes Diagramm, das sich voraussichtlich mehr als einmal ändert, sollte referenziert statt kopiert eingebettet werden.
So wird es Teil Ihrer Dokumentationspraxis
Das Referenced Diagram Macro funktioniert am besten mit einer klaren Konvention, wo maßgebliche Diagramme liegen. Teams, die am meisten davon profitieren, legen meist für jede Diagrammart einen festen Ort fest (Architekturdiagramme im Engineering-Bereich, Prozessabläufe im Operations-Wiki, Organigramme im Personalbereich) und verweisen überall sonst mit dem Makro darauf. So entsteht eine vorhersehbare Struktur: Diagramme sind leicht zu finden, leicht zu aktualisieren und können nicht versehentlich in Varianten zerfallen.
Hat Ihr Team in Confluence bereits viele doppelte Diagramme angesammelt, brauchen Sie für den Umstieg auf Referenzen keine große Aufräumaktion auf einen Schlag. Beginnen Sie mit den Diagrammen, die sich am häufigsten ändern (Systemtopologien, aktive Workflows, Teamstrukturen), und legen Sie die maßgebliche Quelle fest. Ersetzen Sie Kopien mit dem Referenced Diagram Macro, sobald Sie darauf stoßen. Mit der Zeit hält sich Ihre Dokumentation selbst aktuell – wie es kein manueller Prozess kann.
Mehr über das Referenced Diagram Macro und alle Diagrammarten in Capable Diagrams erfahren Sie im Hilfecenter von Capable Diagrams. Oder installieren Sie die App direkt über den Atlassian Marketplace.
Capable Diagrams gehört zur App-Suite von Capable für Confluence Cloud, mit der Teams planen, dokumentieren und zusammenarbeiten, ohne ihre gewohnten Tools zu verlassen.




