🥇Gestaltung in Confluence

Hallo zusammen!

Mein Name ist Masha und ich arbeite als QA-Ingenieurin bei der Tinkoff-Gruppe. Die Arbeit im QA-Bereich erfordert zahlreiche Kommunikationen mit verschiedenen Personen aus unterschiedlichen Teams. Zudem war ich auch Managerin und Dozentin für Bildungsprogramme, weshalb mein Kommunikationsnetzwerk sehr weitreichend war. Irgendwann habe ich einfach aufgegeben: Ich konnte einfach nicht mehr, ich konnte nicht mehr diese unlesbaren Tabellen und Dokumente ausfüllen.

Sicherlich hat sich jeder von Ihnen jetzt das vorgestellt, worüber ich spreche, und einen kalten Schweißausbruch bekommen: Listen von Nachnamen ohne alphabetische Ordnung, Tabellen mit Hunderten von Spalten, bei denen das Layout verschoben ist, Tabellen mit Tausenden von Zeilen, bei denen man seinen Finger über das Mausrad reiben muss, um die Überschrift zu sehen, Tonnen von unnummerierten Anleitungen, Hunderte von E-Mails, die hin und her geschickt werden mit Daten, die man analysieren, systematisieren und in ebenso unlesbare Tabellen stopfen muss.

Und nachdem ich etwas abgekühlt bin, habe ich mich entschieden, diesen Artikel zu schreiben. Ich möchte darüber berichten, wie man vernünftige (und manchmal sogar praktische) nicht-produktbezogene Dokumentation führen kann. Ich hoffe, dass der Artikel im Netz verbreitet wird und das Niveau des Chaos in den Abteilungen neben der Entwicklung ein wenig sinkt, sodass die Menschen (einschließlich mir) etwas glücklicher werden.

Werkzeuge

Produktbezogene Dokumentation wird oft neben dem Code aufbewahrt, was gut ist. Nicht-produktbezogene Dokumentation hingegen wird oft irgendwo abgelegt. Häufig versuchen die Leute, Informationen aus verschiedenen Quellen in Confluence zu übertragen, und wir sind da keine Ausnahme. Daher wird der folgende Bericht darüber sein.

Im Allgemeinen ist Confluence eine fortschrittliche Wiki-Engine. Sie ermöglicht die Arbeit mit Daten in verschiedenen Darstellungsformen: formatierter Text, Tabellen, verschiedene Diagramme. Es ist ein sehr interessantes und mächtiges Werkzeug, aber wenn man nicht weiß, wie man es richtig einsetzt, hat man am Ende einen Haufen unleserlicher Dokumente. Ich werde euch beibringen, wie man es richtig macht!

Makros

Die Hauptmagie von Confluence basiert auf Makros. Es gibt viele verschiedene Makros, die miteinander kombiniert werden können. Sie können kostenpflichtig oder kostenlos sein; im Folgenden finden Sie verschiedene Beispiele für Makros mit Links zur entsprechenden Dokumentation.

Die Benutzeroberfläche für die Arbeit mit Makros ist äußerst einfach. Um ein Makro hinzuzufügen, klicken Sie auf das Pluszeichen und wählen Sie das gewünschte Element aus der Liste.

Wenn ein Makro eigenständig ist, d. h. nichts weiter in sich benötigt, erscheint es als Block.

Wenn für die Funktion eines Makros etwas innerhalb platziert werden muss, wird es als Rahmen dargestellt.

Innerhalb eines Rahmens können Sie beliebig viele andere Elemente unterbringen, solange Ihre Struktur logisch bleibt.

Jedes Makro verfügt über eine Vorschau: So sehen Sie sofort, ob Sie das Makro korrekt ausgefüllt und konfiguriert haben.

Vorlagen

Zusätzlich zu den Makros gibt es ein hilfreiches Tool zur automatischen Befüllung von Inhalten – die Vorlage.
Vorlagen können beim Erstellen jeder Seite verwendet werden: Klicken Sie einfach auf die drei Punkte neben der Schaltfläche „Erstellen“ und wählen Sie die gewünschte Vorlage aus.

Dann wird der gesamte Inhalt, der in der Vorlage steht, in die neu erstellte Seite eingefügt.

Seiten aus Vorlagen kann jeder erstellen, jedoch können nur die Personen, die entsprechende Rechte haben, die Vorlagen selbst erstellen oder bearbeiten. In die Vorlage können zusätzliche Anweisungen hinzugefügt werden, wie die Seite geführt werden soll.

Die Magie der Tabellen

Als Techniker habe ich eine besondere Vorliebe für Tabellen; ich kann fast jede Information darin unterbringen (auch wenn das nicht immer die effektivste Methode ist). Tabellen sind klar, strukturiert, skalierbar und einfach magisch!

Doch selbst so eine wunderbare Sache wie eine Tabelle kann vermasselt werden. Man kann sie jedoch auch geschickt nutzen und sogar verbessern. Mehr dazu weiter unten.

Filterung (kostenpflichtiges Plugin)

Jede riesige, unleserliche Tabelle kann durch Filterung etwas weniger riesig und lesbarer gemacht werden. Dafür kann ein kostenpflichtiges Makro verwendet werden. „Tabellenfilter“.

In dieses Makro muss die Tabelle eingefügt werden (selbst die hässlichste ist in Ordnung, solange sie vollständig eingefügt wird). Im Makro können Spalten für Filter mittels Dropdown-Liste, Textfilter, Zahlenfilter und Datumsfilter ausgewählt werden.

Stellen Sie sich vor, dass alle Informationen zu den Bewerbern für alle Stellenangebote in einer unsortierten Tabelle festgehalten werden. Natürlich kommen die Leute nicht alphabetisch zu den Vorstellungsgesprächen. Sie müssen nur herausfinden, ob Sie bereits ein Gespräch mit einem bestimmten Kandidaten geführt haben. Dazu bringen Sie einfach das Chaos in ein Filter-Makro, fügen einen Textfilter nach Nachname hinzu – und voilà, die Informationen sind auf Ihrem Bildschirm.

Es ist wichtig zu beachten, dass die Filterung großer Tabellen die Systemleistung und die Ladezeiten der Seiten beeinträchtigen kann. Daher ist es eine vorübergehende Lösung, eine große Tabelle zu filtern. Es ist besser, einen Prozess aufzubauen, in dem die Leute keine riesigen, unleserlichen Tabellen erstellen müssen (ein Beispiel für diesen Prozess finden Sie am Ende des Artikels).

Sortierung (kostenpflichtiges Plugin)

Mit einem magischen Makro „Tabellenfilter“ kann auch eine Standard-Sortierung nach beliebiger Spalte festgelegt und die Zeilen nummeriert werden. Oder Sie klicken auf eine beliebige Spalte der Tabelle, die im Filter-Makro enthalten ist, und sie wird nach dieser Spalte sortiert.

Zum Beispiel, wenn Sie dieselbe Tabelle mit Bewerbern haben und herausfinden möchten, wie viele Interviews in einem bestimmten Monat geführt wurden, sortieren Sie nach Datum und freuen Sie sich.

Pivot-Tabellen (kostenpflichtiges Plugin)

Jetzt kommen wir zu einem interessanteren Fall. Stellen Sie sich vor, Ihre Tabelle ist riesig und Sie müssen etwas damit berechnen. Natürlich können Sie sie nach Excel kopieren, die benötigten Berechnungen durchführen und die Daten zurück in Confluence exportieren. Oder Sie verwenden einmalig ein Makro. „Pivot-Tabelle“ und erhalten das gleiche Ergebnis, aber zusätzlich aktualisierbar.

Beispiel: Sie haben eine Tabelle, die Daten aller Mitarbeiter enthält – wo sie sich geografisch befinden und welche Positionen sie innehaben. Um zu zählen, wie viele Personen in jeder Stadt sind, müssen Sie im Makro „Pivot-Tabelle“ die Zeile auswählen, nach der die Daten aggregiert werden (Standort) und die Art der Operation (Addition).

Natürlich kann man nach mehreren Kriterien gleichzeitig gruppieren; alle Möglichkeiten können angesehen werden. in der Dokumentation.

Diagramme (kostenpflichtiges Plugin)

Wie ich bereits sagte, mögen nicht alle Tabellen so sehr wie ich. Leider haben die meisten Manager eine Abneigung gegen sie. Aber alle lieben auffällige, bunte Diagramme.
Die Entwickler von Confluence waren sich dessen sicherlich bewusst (sie haben bestimmt auch Vorgesetzte, die Berichte und Diagramme mögen, wo kämen wir da hin). Deshalb kann man den magischen Makro verwenden, „Diagramm aus Tabelle“. In dieses Makro muss man die Pivot-Tabelle aus dem vorherigen Punkt einfügen, und voila — Ihre grauen, langweiligen Daten sind schön visualisiert.

Natürlich gibt es auch in diesem Makro Einstellungen. Den Link zur Dokumentation jedes Makros finden Sie im Bearbeitungsmodus dieses Makros.

Einfachheit der Aggregation

Die Informationen aus den vorherigen Punkten waren Ihnen sicherlich keine Überraschung. Aber jetzt wissen Sie genau, wie man Makros verwendet, und ich kann zu dem interessanteren Teil des Artikels übergehen.

Kennzeichnungen

Es ist ineffizient, wenn Informationen in einem unstrukturierten Artikel oder einer riesigen Tabelle aufbewahrt werden. Noch schlimmer ist es, wenn Teile dieser Informationen nicht nur unleserlich formatiert sind, sondern auch verstreut in Confluence zu finden sind. Glücklicherweise gibt es die Möglichkeit, verstreute Informationen an einem Ort zu sammeln. Dazu sollten Sie die Tags (allen aus sozialen Netzwerken bekannten Etiketten) verwenden.

Auf jede Seite können beliebig viele Tags hinzugefügt werden. Wenn Sie auf einen Tag klicken, gelangen Sie zu einer Aggregationsseite, auf der Links zu allen Materialien mit diesem Tag sowie zu einer Reihe verwandter Tags zu finden sind. Verwandte Tags sind solche, die häufig auf derselben Seite vorkommen.

Seitenattribute

Zusätzlich können Sie ein interessantes Makro hinzufügen, um Informationen zu strukturieren — „Seitenattribute“. In dieses Makro müssen Sie eine Tabelle mit zwei Spalten einfügen, wobei die erste die Schlüssel und die zweite den Wert des Attributs sein wird. Dabei kann das Makro von der Seite ausgeblendet werden, sodass es den Lesefluss nicht stört, aber die Seite dennoch mit den erforderlichen Schlüsseln versehen bleibt.

Bitte beachten Sie die ID – es ist praktisch, diese zu vergeben, um unterschiedliche Eigenschaften verschiedenen Seiten (oder sogar unterschiedlichen Gruppen von Eigenschaften auf einer Seite) zuzuordnen.

Berichte

Berichte können anhand von Tags erstellt werden. Zum Beispiel makros „Inhaltsbericht“ sammelt alle Seiten mit einem bestimmten Set von Tags.

Ein interessanterer Bericht ist jedoch das Makro „Seitenattributbericht“. Es sammelt ebenfalls alle Seiten mit einem bestimmten Satz an Tags, listet diese jedoch nicht einfach auf, sondern erstellt eine Tabelle (erinnern Sie sich an den Zusammenhang mit dem Anfang des Artikels?), in der die Spalten die Schlüssel der Seitenattribute darstellen.

Das Ergebnis ist eine Pivot-Tabelle, die Informationen aus verschiedenen Quellen zusammenfasst. Praktisch ist, dass sie nützliche Funktionen hat: responsives Design, Sortierung nach beliebigen Spalten. Solch eine Berichtstabelle kann auch innerhalb des Makros konfiguriert werden.

Bei der Konfiguration können bestimmte Spalten aus dem Bericht entfernt, der Standardzustand oder die Anzahl der angezeigten Elemente festgelegt werden. Außerdem kann die Seitenattribut-ID angegeben werden, um nur die relevanten Informationen anzuzeigen.

Zum Beispiel haben Sie eine Vielzahl von Mitarbeiterseiten, und auf diesen Seiten gibt es eine Reihe von Eigenschaften über die Person: welches Niveau sie hat, wo sie sich befindet, wann sie ins Team gekommen ist usw. Diese Eigenschaften sind gekennzeichnet ID = employee_inf. Und es gibt einen zweiten Satz von Eigenschaften auf derselben Seite, die Informationen über die Person als Teil des Teams sammeln: welche Rolle die Person ausfüllt, in welchem Team sie sich befindet usw. Diese Eigenschaften sind gekennzeichnet ID = team_inf. Dann können Sie beim Erstellen des Berichts entweder nur Informationen zu einer ID oder gleich zu zwei IDs ausgeben – je nachdem, was praktischer ist.

Das Schönste an diesem Ansatz ist, dass jeder die für ihn benötigte Informationstabelle erstellen kann, die nichts dupliziert und sich beim Aktualisieren der Hauptseite aktualisiert. Zum Beispiel: Ein Teamleiter interessiert sich nicht dafür, wann seine Entwickler eingestellt wurden, sondern dafür, welche Rolle jeder von ihnen im Team spielt. Der Teamleiter wird einen Bericht für sein Team zusammenstellen. Ein Buchhalter interessiert sich überhaupt nicht dafür, wer welche Rolle spielt, aber die Positionen sind wichtig – er wird sich einen Bericht über die Positionen zusammenstellen. Dabei wird die Informationsquelle nicht dupliziert oder verschoben.

Der abschließende Prozess

Anleitung

So können wir Informationen in Confluence schön strukturieren und effizient aggregieren, indem wir Makros verwenden. Idealerweise sollte neue Informationen direkt strukturiert werden und in alle bereits genutzten Aggregationsmechanismen integriert werden.

Hier kommt die Kombination aus Makros und Vorlagen ins Spiel. Um die Benutzer dazu zu bringen, neue Seiten im gewünschten Format zu erstellen, kann das Makro „Aus Vorlage erstellen“ verwendet werden. Es fügt der Seite einen Button hinzu, durch den beim Klicken eine neue Seite aus der gewählten Vorlage erstellt wird. So stellen Sie sicher, dass die Nutzer sofort im gewünschten Format arbeiten.

In die Vorlage, aus der Sie die Seite erstellen, sollten Sie im Voraus Tags, das Makro „Seitenattribute“ und eine Tabelle mit den benötigten Attributen einfügen. Ich empfehle zudem, Anleitungen hinzuzufügen, welche Werte ausgefüllt werden sollten und welche Eigenschaften verwendet werden.

Der gesamte Prozess würde dann wie folgt aussehen:

Sie erstellen eine Vorlage für Informationen eines bestimmten Typs.
In diese Vorlage fügen Sie Tags und Seitenattribute im Makro ein.
An einer beliebigen Stelle erstellen Sie eine Hauptseite mit einem Button, der beim Klicken eine Unterseite aus der Vorlage generiert.
Sie lassen Benutzer auf die Hauptseite, die potenziell die benötigten Informationen generieren können (im gewünschten Format durch Klicken auf den Button).
Sie erstellen sich einen Bericht über die Eigenschaften der Seite anhand der Tags, die Sie in der Vorlage angegeben haben.
Sie freuen sich: Sie haben alle benötigten Informationen in einem praktischen Format.

Herausforderungen

Als Qualitätsingenieur kann ich mit Zuversicht sagen, dass es nichts Perfektes auf der Welt gibt. Selbst göttliche Tabellen sind nicht perfekt. Und im oben beschriebenen Prozess gibt es einige Fallstricke.

Wenn Sie sich entscheiden, die Namen oder die Eigenschaften der Seite zu ändern, müssen Sie alle bereits erstellten Objekte aktualisieren, damit ihre Daten korrekt im zusammenfassenden Bericht angezeigt werden. Das ist bedauerlich, aber auf der anderen Seite zwingt es dazu, die 'Architektur' Ihres Informationssatzes detailliert zu durchdenken, was eine sehr interessante Aufgabe ist.
Sie müssen eine angemessene Menge an Anweisungen schreiben, wie man Informationsblätter ausfüllt und Tags verwendet. Andererseits können Sie einfach die benötigten Personen mit diesem Artikel kontaktieren.

Beispiel für die Speicherung von nicht-produktbezogener Dokumentation

Durch den oben beschriebenen Prozess kann fast jede Art von Informationen gespeichert werden. Der Vorteil dieses Ansatzes ist seine Vielseitigkeit: Wenn die Benutzer sich daran gewöhnen, erzeugen sie kein Chaos mehr. Ein weiterer großer (aber nicht kostenloser) Vorteil ist die Möglichkeit, in Echtzeit verschiedene Statistiken zu sammeln und ansprechende Diagramme zu erstellen.

Ich gebe ein Beispiel für unseren Prozess zur Dokumentation von Informationen über das Team.

Für jede Person im Team haben wir beschlossen, eine Mitarbeitendenkarte zu erstellen. Entsprechend gibt es eine Vorlage, nach der jede neue Person ihre Karte erstellt und dort alle persönlichen Informationen festhält.

Wie Sie sehen, haben wir eine detaillierte Tabelle mit Eigenschaften, und sofort gibt es Anweisungen, wie diese Seite geführt werden soll. Ein Teil der Tags wird von den Mitarbeitern gemäß den Anweisungen gesetzt, in der Vorlage sind nur die grundlegenden: Tag der Karte employee-card, Tag der Richtung direction-involve und Team-Tag team-qa.

Am Ende, nachdem jeder seine eigene Karte erstellt hat, ergibt sich eine vollständige Tabelle mit Informationen zu den Mitarbeitern. Diese Informationen können an verschiedenen Stellen genutzt werden. Ressourcenmanager können sich allgemeine Tabellen zusammenstellen, während Teamleiter – Team-Tabellen erstellen, indem sie den Team-Tag in die Auswahl einfügen.

Anhand der Tags können verschiedene Zusammenfassungen gesehen werden, beispielsweise zu qa-upgrade-plan alle Aufgaben zur Weiterentwicklung von QA angezeigt werden. Jeder Mitarbeiter führt in seiner Karte eine wichtige Historie und seinen Entwicklungsplan – er erstellt eine untergeordnete Seite aus der Vorlage für Entwicklungspläne.