🥇Entwurf in Confluence

Hallo zusammen!

Ich heiße Masha und arbeite als Qualitätsingenieurin in der Tinkoff Unternehmensgruppe. Die QA-Arbeit erfordert viele Kommunikationen mit verschiedenen Leuten aus unterschiedlichen Teams, und ich war außerdem Managerin und Dozentin für Bildungsprogramme, weshalb mein Kommunikationsnetz maximal weit gefächert war. Und irgendwann war ich so frustriert: Ich habe erkannt, dass ich es nicht mehr ertragen kann, unzählige unleserliche Tabellen und Dokumente auszufüllen.

Wahrscheinlich hat sich jeder von euch jetzt das vorgestellt, worüber ich spreche, und ist ins Schwitzen geraten: Listen von Nachnamen ohne alphabetische Reihenfolge, Tabellen mit Hunderten von Spalten mit verschobener Formatierung, Tabellen mit Tausenden von Zeilen, bei denen man seinen Finger am Mausrad reiben muss, um die Überschrift zu sehen, Tonnen von unnummerierten Anleitungen, Hunderte von weitergeleiteten E-Mails mit Daten, die analysiert und systematisiert und in ebenso unleserliche Tabellen gesteckt werden müssen.

Und als ich mich etwas beruhigt hatte, beschloss ich, diesen Artikel zu schreiben. Ich möchte darüber berichten, wie man normale (manchmal sogar bequeme) nicht-produktbezogene Dokumentation führt. Ich hoffe, dass der Artikel sich im Netz verbreitet und das Niveau des Chaos in den Abteilungen, die mit Entwicklung zusammenhängen, zumindest ein wenig sinkt, und die Leute (mich eingeschlossen) ein kleines bisschen glücklicher werden.

Werkzeuge

Produktdokumentation wird oft direkt neben dem Code aufbewahrt, was gut ist. Nicht-produktbezogene Dokumentation wird normalerweise irgendwo hinterlegt. Oft versuchen die Leute, Informationen aus verschiedenen Quellen nach Confluence zu übertragen, und wir sind keine Ausnahme. Daher handelt die gesamte folgende Erzählung davon.

Im Grunde ist Confluence eine erweiterte Wiki-Engine. Sie ermöglicht die Arbeit mit Daten in verschiedenen Darstellungsformen: formatierter Text, Tabellen, verschiedene Diagramme. Es ist ein sehr interessantes und leistungsstarkes Werkzeug, aber wenn man nicht weiß, wie man es vorbereitet, erhält man eine weitere Ablage unleserlicher Dokumente. Ich werde euch beibringen, wie man das richtig macht!

Makros

Fast die gesamte Magie von Confluence beruht auf Makros. Es gibt viele Makros, und sie können miteinander kombiniert werden. Es gibt kostenpflichtige und kostenlose, und im Folgenden werden verschiedene Beispiele für Makros mit Links zur Dokumentation vorgestellt.

Die Benutzeroberfläche für die Arbeit mit Makros ist sehr einfach. Um ein Makro hinzuzufügen, muss man auf das Pluszeichen klicken und das gewünschte Element aus der Liste auswählen.

Wenn das Makro autark ist, d. h. nichts anderes in sich einfügen muss, sieht es wie ein Block aus.

Wenn für die Funktion des Makros etwas hineingelegt werden muss, sieht es wie ein Rahmen aus.

Dabei kann man beliebig viele andere innerhalb eines Rahmens unterbringen, solange in Ihrer Pyramide eine Logik vorhanden ist.

Jedes Makro hat eine Vorschau: darin sieht man sofort, ob man das Makro richtig ausgefüllt und eingestellt hat.

Vorlagen

Neben Makros gibt es ein nützliches Werkzeug für die automatische Befüllung von Inhalten – das ist die Vorlage.
Vorlagen können bei der Erstellung jeder Seite verwendet werden: einfach auf die drei Punkte neben der Schaltfläche „Erstellen“ klicken und die gewünschte Vorlage auswählen.

Dann wird der gesamte Inhalt, der in der Vorlage enthalten ist, in die erstellte Seite eingefügt.

Jeder kann Seiten aus Vorlagen erstellen, aber nur diejenigen mit den entsprechenden Rechten können die Vorlagen selbst erstellen oder bearbeiten. In die Vorlage können zusätzliche Anweisungen aufgenommen werden, wie die Seite geführt werden soll.

Die Magie der Tabellen

Tatsächlich liebe ich als Techniker Tabellen und kann fast jede Information darin unterbringen (auch wenn das nicht immer effizient ist). Tabellen selbst sind klar, strukturiert, skalierbar, magisch!

Aber selbst eine so wunderbare Entität wie eine Tabelle kann verderben werden. Man kann sie aber auch geschickt nutzen und sogar verbessern. Darum geht es im Folgenden.

Filterung (kostenpflichtiges Plugin)

Jede große, unleserliche Tabelle kann durch Filterung etwas weniger groß und etwas leserlicher gemacht werden. Dafür kann man ein kostenpflichtiges Makro verwenden. „Tabellenfilter“.

In dieses Makro muss eine Tabelle eingefügt werden (man kann sogar die hässlichste verwenden, Hauptsache, man steckt sie ganz hinein). Im Makro können Spalten für den Filter aus einer Dropdown-Liste, einem Textfilter, einem Zahlenfilter und einem Datumsfilter gewählt werden.

Stellen Sie sich vor, dass alle Informationen über Kandidaten für alle Stellen in einer tabellarischen Liste erfasst werden. Natürlich ist diese nicht sortiert – die Leute kommen ja nicht alphabetisch zu Vorstellungsgesprächen. Und Sie müssen herausfinden, ob Sie bereits ein Gespräch mit einem bestimmten Bewerber geführt haben. Man muss einfach dieses Chaos in ein Filter-Makro stecken, einen Textfilter nach dem Nachnamen hinzufügen – und voilà, die Informationen sind auf dem Bildschirm.

Es ist zu beachten, dass die Filterung großer Tabellen die Systemleistung und die Ladezeiten von Seiten beeinflussen kann. Daher ist es nur eine vorübergehende Lösung, eine große Tabelle in einen Filter zu stecken. Besser wäre es, einen Prozess zu gestalten, in dem die Menschen 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 jeder Spalte festgelegt und die Zeilen nummeriert werden. Alternativ kann man auf eine beliebige Spalte der Tabelle klicken, die in das Filter-Makro eingefügt wurde, und die Sortierung erfolgt nach dieser Spalte.

Beispielsweise haben Sie dieselbe Tabelle mit Bewerbern und möchten ermitteln, wie viele Vorstellungsgespräche in einem bestimmten Monat stattgefunden haben – 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önnte man sie in Excel kopieren, die gewünschten Berechnungen vornehmen und die Daten zurück in Confluence exportieren. Man kann auch einmalig das Makro „Pivot-Tabelle“ anwenden und das gleiche Ergebnis erhalten, nur dass es auch aktualisiert wird.

Beispielsweise haben Sie eine Tabelle, die alle Mitarbeiterdaten enthält – wo sie sich geografisch befinden und welche Positionen sie einnehmen. Um zu berechnen, wie viele Personen sich in jeder Stadt befinden, müssen Sie im Makro „Pivot-Tabelle“ die Zeile auswählen, nach der die Daten aggregiert werden (Standort) und den Operationstyp (Summierung).

Natürlich können mehrere Merkmale gleichzeitig gruppiert werden, sämtliche Möglichkeiten können Sie sich ansehen. Dokumentation.

Diagramme (kostenpflichtiges Plugin)

Wie ich schon sagte, lieben nicht alle Tabellen so sehr wie ich. Leider mögen die meisten Manager sie überhaupt nicht. Aber alle lieben bunte, auffällige Diagramme.
Die Schöpfer von Confluence wussten das natürlich (sie haben sicherlich auch Vorgesetzte, die Berichte und Diagramme lieben, wo kämen wir da hin). Daher können Sie das magische Makro „Diagramm aus Tabelle“. In dieses Makro müssen Sie die Pivot-Tabelle aus dem vorherigen Punkt einfügen, und voila – Ihre grauen, langweiligen Daten werden ansprechend visualisiert.

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

Einfachheit der Aggregation

Die Informationen aus den vorherigen Punkten werden Sie sicherlich nicht überrascht haben. Aber jetzt wissen Sie genau, wie man Makros nutzt, und ich kann zu dem interessanteren Teil des Artikels übergehen.

Seitenattribute

Für die Strukturierung von Informationen kann man ein weiteres interessantes Makro hinzufügen - „Seitenattribute“. In dieses müssen Sie eine Tabelle mit zwei Spalten einfügen, wobei die erste den Schlüssel und die zweite den Wert des Attributs darstellt. Dabei kann das Makro auf der Seite verborgen werden, damit es das Lesen des Inhalts nicht stört, aber die Seite wird dennoch mit den benötigten Schlüsseln gekennzeichnet.

Achten Sie auf die ID - es ist praktisch, diese festzulegen, um unterschiedliche Gruppen von Attributen auf verschiedene Seiten (oder sogar unterschiedliche Gruppen von Attributen auf einer Seite) anzuwenden.

Berichte

Anhand der Tags können Berichte erstellt werden. Zum Beispiel sammelt das Makro „Inhaltsbericht“ alle Seiten mit einem bestimmten Satz von Tags.

Ein interessanterer Bericht ist jedoch das Makro „Seitenattributbericht“. Es sammelt ebenfalls alle Seiten mit einem bestimmten Satz von Tags, zeigt jedoch nicht einfach nur eine Liste an, sondern erstellt eine Tabelle (merken Sie die Verbindung zum ersten Teil des Artikels?), in der die Spalten die Schlüssel der Seitenattribute sind.

So ergibt sich eine Pivot-Tabelle mit Informationen aus verschiedenen Quellen. Schön ist, dass sie über nützliche Funktionen verfügt: responsive Layout, Sortierung nach beliebiger Spalte. Außerdem kann diese Berichtstabelle innerhalb des Makros konfiguriert werden.

Bei der Konfiguration können bestimmte Spalten aus dem Bericht entfernt, der Standardzustand oder die Anzahl der angezeigten Einträge festgelegt werden. Man kann auch die ID des Seitenattributs angeben, um nur die gewünschten Informationen anzuzeigen.

Zum Beispiel haben Sie eine Vielzahl von Mitarbeiterseiten, und diese Seiten haben eine Reihe von Eigenschaften über eine Person: welches Niveau sie haben, wo sie sich befinden, wann sie ins Team gekommen sind usw. Diese Eigenschaften sind gekennzeichnet ID = employee_inf. Und es gibt eine zweite Reihe von Eigenschaften auf derselben Seite, die Informationen über die Person als Teil des Teams sammeln: welche Rolle die Person einnimmt, in welchem Team sie ist usw. Diese Eigenschaften sind gekennzeichnet ID = team_inf. Dann können Sie beim Erstellen des Berichts Informationen zu einem einzigen ID oder sofort zu beiden – je nach Bedarf – abrufen.

Die Schönheit dieses Ansatzes liegt darin, dass jeder die benötigte Informationstabelle erstellen kann, die nichts dupliziert und sich beim Aktualisieren der Hauptseite aktualisiert. Zum Beispiel: Ein Teamleiter ist nicht interessiert, wann seine Entwickler eingestellt wurden, aber wichtig ist, welche Rolle jeder von ihnen im Team spielt. Der Teamleiter wird sich einen Bericht über das Team zusammenstellen. Ein Buchhalter hingegen interessiert sich überhaupt nicht dafür, wer welche Rolle spielt, aber die Positionen sind wichtig – er wird sich einen Bericht über die Positionen erstellen. Dabei wird die Informationsquelle nicht dupliziert oder verschoben.

Der finale Prozess

Anleitung

So können wir Informationen in Confluence schön strukturieren und effizient aggregieren, indem wir Makros verwenden. Idealerweise sollte die neue Information sofort strukturiert sein und in alle bereits verwendeten Aggregationsmechanismen eingefügt werden.

Hier kommt die Kombination aus Makros und Vorlagen ins Spiel. Um die Leute dazu zu bringen, neue Seiten im richtigen Format zu erstellen, kann das Makro „Aus Vorlage erstellen“ verwendet werden. Es fügt der Seite eine Schaltfläche hinzu, mit der beim Klicken eine neue Seite aus der gewünschten Vorlage erstellt wird. So zwingen Sie die Leute, sofort im gewünschten Format zu arbeiten.

In die Vorlage, aus der Sie eine Seite erstellen, sollten im Voraus Tags, das Makro „Seiteigenschaften“ und die Tabelle der benötigten Eigenschaften eingefügt werden. Ich empfehle außerdem, Anweisungen hinzuzufügen, welche Werte die Seite haben sollte und welche Eigenschaften sie besitzen sollte.

Dann wird der finale Prozess folgendermaßen aussehen:

Sie erstellen eine Vorlage für Informationen eines bestimmten Typs.
In diese Vorlage fügen Sie Tags und Eigenschaften der Seite im Makro hinzu.
An jedem beliebigen Ort erstellen Sie eine Hauptseite mit einer Schaltfläche, durch die beim Klick eine untergeordnete Seite aus einer Vorlage erstellt wird.
Sie lassen Benutzer auf die Hauptseite zu, die potenziell die benötigten Informationen generieren (basierend auf der benötigten Vorlage, indem sie auf die Schaltfläche klicken).
Sie stellen sich einen Bericht über die Eigenschaften der Seite mithilfe der von Ihnen in der Vorlage angegebenen Tags zusammen.
Sie freuen sich: Sie haben alle benötigten Informationen in einem praktischen Format.

Herausforderungen

Als Qualitätsingenieur kann ich mit Überzeugung sagen, dass es nichts Perfektes in der Welt gibt. Selbst göttliche Tabellen sind nicht perfekt. Und in dem oben genannten Prozess gibt es einige Tücken.

Wenn Sie beschließen, die Namen oder die Zusammensetzung der Seiteneigenschaften zu ändern, müssen Sie alle bereits erstellten Objekte aktualisieren, damit ihre Daten korrekt in den Gesamtbericht übertragen werden. Das ist bedauerlich, zwingt Sie aber andererseits dazu, die „Architektur“ Ihres Informationssets sorgfältig zu durchdenken, was eine sehr interessante Aufgabe darstellt.
Sie müssen eine beträchtliche Anzahl von Anweisungen zum Ausfüllen der Informationstabelle und zur Verwendung von Tags schreiben. Andererseits können Sie einfach allen betroffenen Personen diesen Artikel zusenden.

Beispiel für die Speicherung von nicht-produktbezogener Dokumentation

Über den oben beschriebenen Prozess kann die Speicherung fast beliebiger Informationen organisiert werden. Der Vorteil des Ansatzes ist, dass er universell ist: Wenn Benutzer sich daran gewöhnen, erzeugen sie kein Durcheinander mehr. Ein weiterer großer (aber nicht kostenloser) Vorteil ist die Möglichkeit, verschiedene Statistiken in Echtzeit zu sammeln und daraus schöne Diagramme zu erstellen.

Ich werde ein Beispiel für unseren Informationsprozess über das Team geben.

Für jede Person im Team haben wir beschlossen, eine Mitarbeiterkarte zu erstellen. Dementsprechend haben wir eine Vorlage, anhand derer jede neue Person diese Karte erstellt und alle persönlichen Informationen darin pflegt.

Wie Sie sehen, haben wir eine ausführliche Tabelle der Eigenschaften und sofort Anweisungen, wie genau diese Seite zu führen ist. Ein Teil der Tags wird von den Mitarbeitern selbst gemäß den Anweisungen gesetzt, in der Vorlage sind nur die grundlegenden: Tag der Karte employee-card, Tag der Richtung direction-involve und Tag des Teams team-qa.

Insgesamt ergibt sich eine vollständige Tabelle mit Informationen zu den Mitarbeitern, nachdem jeder seine eigene Karte erstellt hat. Diese Informationen können an verschiedenen Stellen verwendet werden. Ressourcenmanager können allgemeine Tabellen erstellen, während Teamleiter die Teambasierte Tabellen erstellen, indem sie die Tags des Teams hinzufügen.

Anhand der Tags lassen sich verschiedene Übersichten erstellen, zum Beispiel zu qa-upgrade-plan es werden alle Aufgaben zur Weiterentwicklung von QA angezeigt. Dabei führt jeder Mitarbeiter in seiner Karte eine wichtige Geschichte und seinen Entwicklungsplan — er erstellt eine untergeordnete Seite aus der Vorlage für Entwicklungspläne.