Hallo an alle!
Mein Name ist Masha, ich arbeite als Qualitätssicherungsingenieurin in der Tinkoff-Unternehmensgruppe. Qualitätssicherungsarbeit beinhaltet viel Kommunikation mit verschiedenen Leuten aus verschiedenen Teams, und ich war auch Manager und Dozent von Bildungsprogrammen, sodass meine Kommunikationskarte so breit wie möglich war. Und irgendwann explodierte ich: Mir wurde klar, dass ich nicht mehr, ich kann, ich kann nicht mehr höllisch Unmengen unleserlicher Tabellen und Dokumente ausfüllen kann.
Sicherlich hat sich jeder von Ihnen jetzt vorgestellt, wovon ich rede, und ist in kalten Schweiß ausgebrochen: Listen mit Nachnamen ohne alphabetische Reihenfolge, Tabellen mit Hunderten von Spalten mit schlampigem Layout, Tabellen mit Tausenden von Zeilen, in denen man den Finger wegradieren muss am Mausrad, um nach Überschriften zu suchen, Tonnen von Seiten mit nicht nummerierten Anweisungen, Hunderte von aneinander gesendeten Briefen mit Daten, die analysiert und systematisiert und in dieselben unleserlichen Tabellen gestopft werden müssen.
Und als ich mich etwas abgekühlt hatte, beschloss ich, diesen Artikel zu schreiben. Ich werde darüber sprechen, wie Sie normalerweise (manchmal sogar bequem) eine Vielzahl von Nicht-Produktdokumentationen verwalten können. Ich hoffe, dass der Artikel über das Netzwerk verbreitet wird und das Adish-Niveau in den an die Entwicklung angrenzenden Abteilungen zumindest leicht sinkt und die Menschen (einschließlich mir) etwas glücklicher werden.
Werkzeuge
Die Produktdokumentation wird häufig zusammen mit dem Code aufbewahrt, was eine gute Sache ist. Und Dokumentation, die nicht zum Produkt gehört, wird normalerweise irgendwo gespeichert. Oftmals versuchen Menschen, Informationen von verschiedenen Orten in Confluence einzubringen, und wir bilden da keine Ausnahme. Der Rest der Geschichte dreht sich also um ihn.
Im Allgemeinen ist Confluence eine fortschrittliche Wiki-Engine. Es ermöglicht Ihnen, mit Daten in verschiedenen Darstellungsarten zu arbeiten: Text mit Formatierung, Tabellen, verschiedene Diagramme. Dies ist ein sehr interessantes und leistungsstarkes Tool, aber wenn Sie nicht wissen, wie man es zubereitet, erhalten Sie einen weiteren Dump unleserlicher Dokumente. Ich werde dir das Kochen beibringen!
Makros
Fast die gesamte Magie von Confluence basiert auf Makros. Es gibt viele Makros, die miteinander kombiniert werden können. Sie sind kostenpflichtig und kostenlos, außerdem wird es verschiedene Beispiele für Makros mit Links zur Dokumentation dazu geben.
Die Schnittstelle zum Arbeiten mit Makros ist so einfach wie möglich. Um ein Makro hinzuzufügen, müssen Sie auf das Pluszeichen klicken und das gewünschte Element aus der Liste auswählen.
Wenn das Makro autark ist, also nicht das Einfügen von etwas anderem in sich selbst erfordert, sieht es wie ein Block aus.
Wenn ein Makro etwas darin benötigt, um zu funktionieren, sieht es wie eine Box aus.
Gleichzeitig können Sie beliebig viele andere in einen Rahmen einfügen, solange Ihre Pyramide logisch ist.
Für jedes Makro gibt es eine Vorschau: Sie zeigt sofort an, ob Sie das Makro richtig ausgefüllt und konfiguriert haben.
Patterns
Neben Makros gibt es ein praktisches Tool zum Vorabfüllen von Inhalten – eine 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.
Anschließend wird der gesamte Inhalt der Vorlage zur erstellten Seite hinzugefügt.
Jeder kann Seiten aus Vorlagen erstellen, aber nur wer die Rechte hat, selbst Vorlagen zu erstellen oder zu bearbeiten, kann Seiten erstellen. Sie können der Vorlage zusätzliche Anweisungen hinzufügen, wie die Seite gepflegt werden soll.
Tischmagie
Eigentlich liebe ich als Technikfreak Tabellen sehr und kann fast jede Information darin verpacken (obwohl das nicht immer effektiv ist). Die Tabellen selbst sind klar, strukturiert, skalierbar, magisch!
Aber auch ein so wunderbares Gebilde wie ein Tisch kann verwöhnt werden. Und es kann erfolgreich eingesetzt und sogar verbessert werden. Mehr dazu weiter unten.
Filtern (kostenpflichtiges Plugin)
Jede große, unleserliche Tabelle kann durch Filtern etwas kleiner und etwas besser lesbar gemacht werden. Dazu können Sie ein kostenpflichtiges Makro verwenden .
Innerhalb dieses Makros müssen Sie eine Tabelle verschieben (selbst die hässlichste ist möglich, die Hauptsache ist, sie vollständig zu verschieben). Im Makro können Sie Spalten für Dropdown-Filter, Textfilter, numerischen Filter und Datumsfilter auswählen.
Stellen Sie sich vor, dass alle Informationen zu Kandidaten für alle offenen Stellen in einer tabellarischen Liste erfasst werden. Natürlich unsortiert – die Leute kommen nicht in alphabetischer Reihenfolge zu Vorstellungsgesprächen. Und Sie müssen verstehen, ob Sie schon einmal ein Vorstellungsgespräch mit einem bestimmten Bewerber geführt haben. Sie müssen nur diese Hölle in ein Filtermakro einfügen, einen Textfilter nach Nachnamen hinzufügen – und voilà, die Informationen werden auf Ihrem Bildschirm angezeigt.
Es ist erwähnenswert, dass das Filtern großer Tabellen die Systemleistung und die Ladezeit der Seite beeinträchtigen kann. Daher ist das Einfügen einer großen Tabelle in den Filter eine vorübergehende Krücke. Es ist besser, einen Prozess aufzubauen, bei dem die Leute keine riesigen unlesbaren Tabellen erstellen müssen (an Ein Beispiel für den Prozess finden Sie am Ende des Artikels.
Sortieren (kostenpflichtiges Plugin)
Mit Magic Macro Sie können auch die Standardsortierung für jede Spalte festlegen und die Zeilen nummerieren. Oder klicken Sie auf eine beliebige Spalte der in das Filtermakro eingefügten Tabelle und die Sortierung erfolgt nach dieser Spalte.
Sie haben zum Beispiel die gleiche Tabelle mit Bewerbern und müssen herausfinden, wie viele Vorstellungsgespräche in einem bestimmten Monat stattgefunden haben – sortieren Sie nach Datum und freuen Sie sich.
Pivot-Tabellen (kostenpflichtiges Plugin)
Kommen wir nun zu einem interessanteren Fall. Stellen Sie sich vor, Ihr Tisch ist riesig und Sie müssen etwas darauf berechnen. Natürlich können Sie es nach Excel kopieren, Ihren Bedarf berechnen und die Daten wieder in Confluence hochladen. Können Sie ein Makro einmal anwenden? und das gleiche Ergebnis erhalten, nur aktualisiert.
Beispiel: Sie haben eine Tabelle, die die Daten aller Mitarbeiter enthält – wo sie sich geografisch befinden und welche Positionen sie innehaben. Um zu berechnen, wie viele Menschen sich in jeder Stadt befinden, 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 können Sie auch nach mehreren Kriterien gleichzeitig gruppieren, dann sehen Sie alle Möglichkeiten .
Diagramme (kostenpflichtiges Plugin)
Wie gesagt, nicht jeder liebt Tische so sehr wie ich. Leider mögen sie die meisten Manager überhaupt nicht. Aber jeder liebt leuchtende Farbkarten.
Die Macher von Confluence wussten das sicherlich (sicherlich haben sie auch Chefs, die Berichte und Diagramme lieben, was wären sie ohne sie). Daher können Sie das Magic-Makro verwenden . In dieses Makro müssen Sie die Pivot-Tabelle aus dem vorherigen Absatz einfügen, und voilà – Ihre langweiligen grauen Daten werden wunderschön visualisiert.
Selbstverständlich verfügt dieses Makro auch über Einstellungen. Einen Link zur Dokumentation für jedes Makro finden Sie im Bearbeitungsmodus dieses Makros.
Einfache Aggregation
Die Informationen aus den vorherigen Absätzen waren für Sie wahrscheinlich keine Offenbarung. Aber jetzt wissen Sie definitiv, wie man Makros verwendet, und ich kann zum interessanteren Teil des Artikels übergehen.
Stichworte
Es ist schlimm, wenn Menschen Informationen in einem unstrukturierten Artikel oder einer riesigen Tabelle speichern. Noch schlimmer ist es, wenn Teile dieser Informationen nicht nur unlesbar sind, sondern auch über die Weiten von Confluence verstreut sind. Glücklicherweise ist es möglich, verstreute Informationen an einem Ort zu sammeln. Dafür müssen Sie verwenden (Tags, die jedem in sozialen Netzwerken bekannt sind).
Jeder Seite können beliebig viele Tags hinzugefügt werden. Wenn Sie auf ein Tag klicken, gelangen Sie zu einer Aggregationsseite mit Links zu allen Inhalten mit diesem Tag sowie einer Reihe verwandter Tags. Verwandte Tags sind solche, die häufig auf derselben Seite erscheinen.
Seiteneigenschaften
Sie können der Seite ein weiteres interessantes Makro zur Strukturierung von Informationen hinzufügen - . Darin müssen Sie eine Tabelle mit zwei Spalten einreichen, wobei die erste der Schlüssel und die zweite der Wert der Eigenschaft ist. Darüber hinaus kann das Makro auf der Seite ausgeblendet werden, sodass es das Lesen des Inhalts nicht beeinträchtigt, die Seite jedoch weiterhin mit den erforderlichen Schlüsseln markiert wird.
Achten Sie auf die ID – es ist praktisch, sie so einzustellen, dass verschiedene Gruppen von Eigenschaften auf verschiedenen Seiten (oder sogar verschiedene Gruppen von Eigenschaften auf einer Seite) hängen.
Berichte
Mithilfe von Tags können Sie Berichte sammeln. Zum Beispiel Makro sammelt alle Seiten mit einem bestimmten Satz von Tags.
Ein interessanterer Bericht ist jedoch ein Makro . Es sammelt auch alle Seiten mit einem bestimmten Satz von Tags, listet sie aber nicht nur auf, sondern erstellt eine Tabelle (erkennen Sie den Zusammenhang mit dem Anfang des Artikels?), in der die Spalten die Schlüssel der Seiteneigenschaften sind.
Es stellt sich eine zusammenfassende Tabelle mit Informationen aus verschiedenen Quellen heraus. Es ist schön, dass es über praktische Funktionen verfügt: adaptives Layout, Sortieren nach jeder Spalte. Außerdem kann eine solche Berichtstabelle innerhalb des Makros konfiguriert werden.
Bei der Konfiguration können Sie einige Spalten aus dem Bericht entfernen, den Standardstatus oder die Anzahl der angezeigten Datensätze festlegen. Sie können die Seiteneigenschafts-ID auch so festlegen, dass nur die von Ihnen benötigten Informationen angezeigt werden.
Wenn Sie beispielsweise viele Mitarbeiterseiten haben, enthalten diese Seiten eine Reihe von Eigenschaften über eine Person: auf welcher Ebene sie sich befindet, wo sie sich befindet, wann sie dem Team beigetreten ist und so weiter. Diese Eigenschaften sind gekennzeichnet id = Employee_inf. Und auf derselben Seite gibt es einen zweiten Satz von Eigenschaften, der Informationen über eine Person als Teil eines Teams enthält: welche Rolle die Person spielt, in welchem Team sie ist und so weiter. Diese Eigenschaften sind gekennzeichnet ID = team_inf. Beim Erstellen eines Berichts können Sie dann nur Informationen für eine oder zwei IDs gleichzeitig anzeigen – je nachdem, was bequemer ist.
Das Schöne an diesem Ansatz ist, dass jeder die benötigte Informationstabelle zusammenstellen kann, die nichts dupliziert und aktualisiert wird, wenn die Hauptseite aktualisiert wird. Zum Beispiel: Einem Teamleiter ist es egal, wann seine Entwickler einen Job bekommen, aber es ist wichtig, welche Rolle jeder von ihnen im Team spielt. Der Teamleiter erstellt einen Bericht über das Team. Und dem Buchhalter ist es egal, wer welche Rolle ausübt, aber die Positionen sind wichtig – er wird einen Bericht über die Positionen sammeln. In diesem Fall erfolgt keine Vervielfältigung oder Weitergabe der Informationsquelle.
Endgültiger Prozess
Unterricht
So können wir in Confluence am Beispiel von Makros Informationen schön strukturieren und effektiv aggregieren. Im Idealfall müssen Sie jedoch sicherstellen, dass neue Informationen sofort strukturiert werden und in alle bereits verwendeten Aggregationsmechanismen gelangen.
Hier helfen eine Reihe von Makros und Vorlagen. Um Benutzer dazu zu bringen, neue Seiten im richtigen Format zu erstellen, können Sie das Makro „Aus Vorlage erstellen“ verwenden. Es fügt der Seite eine Schaltfläche hinzu, durch Klicken wird eine neue Seite aus der von Ihnen benötigten Vorlage erstellt. Auf diese Weise zwingen Sie die Leute dazu, sofort in dem von Ihnen benötigten Format zu arbeiten.
In der Vorlage, aus der Sie eine Seite erstellen können, müssen Sie im Voraus Beschriftungen, das Makro „Seiteneigenschaften“ und eine Tabelle mit den Eigenschaften hinzufügen, die Sie benötigen. Ich empfehle außerdem, Anweisungen dazu hinzuzufügen, mit welchen Werten die Seite gefüllt werden soll und welche Eigenschaftswerte sie haben.
Dann sieht der endgültige Prozess so aus:
- Sie erstellen eine Vorlage für eine bestimmte Art von Informationen.
- Fügen Sie in dieser Vorlage Beschriftungen und Seiteneigenschaften in einem Makro hinzu.
- Erstellen Sie an einem beliebigen Ort eine Stammseite mit einer Schaltfläche, auf die eine untergeordnete Seite aus der Vorlage erstellt wird.
- Starten Sie auf der Stammseite der Benutzer, die möglicherweise die erforderlichen Informationen generieren (gemäß der gewünschten Vorlage, indem Sie auf die Schaltfläche klicken).
- Erstellen Sie mithilfe der Tags, die Sie in der Vorlage angegeben haben, einen Bericht über die Eigenschaften der Seite.
- Freuen Sie sich: Sie haben alle Informationen, die Sie benötigen, in einem praktischen Format.
Fallstricke
Als Qualitätsingenieur kann ich mit Sicherheit sagen, dass es auf der Welt nichts Perfektes gibt. Sogar göttliche Tische sind unvollkommen. Und der obige Prozess birgt Fallstricke.
- Wenn Sie sich entscheiden, die Namen oder die Zusammensetzung der Seiteneigenschaften zu ändern, müssen Sie alle bereits erstellten Objekte aktualisieren, damit ihre Daten korrekt in den zusammenfassenden Bericht übernommen werden. Das ist traurig, aber andererseits zwingt es Sie dazu, im Detail über die „Architektur“ Ihres Informationssatzes nachzudenken, was eine sehr interessante Aufgabe ist.
- Sie müssen eine ganze Reihe von Anweisungen zum Ausfüllen der Informationstabellen und zur Verwendung der Tags schreiben. Aber andererseits können Sie diesen Artikel einfach den richtigen Leuten vorwerfen.
Ein Beispiel für die Speicherung von Nicht-Produktdokumentation
Durch den oben beschriebenen Prozess können Sie die Speicherung nahezu aller Informationen organisieren. Das Schöne an dem Ansatz ist, dass er universell ist: Sobald sich Benutzer daran gewöhnt haben, machen sie kein Chaos mehr. Ein großes (aber nicht kostenloses) Plus ist auch die Möglichkeit, im Handumdrehen verschiedene Statistiken zu sammeln und schöne Diagramme darauf zu zeichnen.
Ich werde ein Beispiel für unseren Prozess der Pflege von Informationen über das Team geben.
Für jede Person im Team haben wir beschlossen, eine Mitarbeiterkarte zu erstellen. Dementsprechend haben wir eine Vorlage, nach der jeder neue Mensch diese Karte für sich erstellt und darin alle seine persönlichen Daten festhält.
Wie Sie sehen, verfügen wir über eine detaillierte Tabelle mit Eigenschaften und sofort über Anweisungen zur Pflege dieser Seite. Einige der Tags werden von den Mitarbeitern selbst nach Anleitung angebracht, in der Vorlage nur die wichtigsten: der Kartenanhänger Mitarbeiterkarte, Richtungsmarkierung Richtung-einbeziehen und Befehls-Tag Team-QA.
Dadurch entsteht, nachdem jeder für sich eine Karte erstellt hat, eine vollständige Tabelle mit Informationen zu den Mitarbeitern. Diese Informationen können an verschiedenen Stellen genutzt werden. Ressourcenmanager können allgemeine Tabellen für sich selbst sammeln, und Teamleiter können Befehlstabellen sammeln, indem sie der Auswahl ein Team-Tag hinzufügen.
Nach Tags können Sie verschiedene Zusammenfassungen anzeigen, beispielsweise nach QA-Upgrade-Plan Alle Aufgaben zur QS-Entwicklung werden angezeigt. Gleichzeitig behält jede Person in ihrer Mitarbeiterkarte eine wichtige Geschichte und ihren eigenen Entwicklungsplan – er erstellt eine verschachtelte Seite aus der Vorlage für Entwicklungspläne.
Abschluss
Bewahren Sie alle Unterlagen so auf, dass Sie sich nicht dafür schämen müssen und die Benutzer keinen unerträglichen Schaden erleiden!
Ich hoffe wirklich, dass der Artikel nützlich ist und Ordnung in die gesamte Dokumentation der Welt kommt.
Source: habr.com