Tools und Connections dokumentieren | Tipps Tuesday #004

[RolandSchubert]

Tue ist das gerade wirklich? Schreibe ich hier einen Beitrag zur Dokumentation vor Workflows? Vermutlich hätte eine Wette, dass das irgendwann passieren würde, vor gar nicht so langer Zeit noch eine richtig gute Quote erzielt … aber man lernt ja schließlich dazu.

Eigentlich sind Alteryx-Workflows ja ziemlich selbsterklärend. Eigentlich. Aber wenn man nach einiger Zeit (da sind nicht einmal Jahre oder Monate erforderlich, manchmal reichen schon Tage) sein eigenes Werk anschaut, um vielleicht noch eine Kleinigkeit zu ergänzen oder anzupassen, taucht dann doch die Frage auf, was da genau passiert. Und wenn sich das jemand anschaut, der es nicht selbst geschrieben hat … wir wollen uns das gar nicht weiter vorstellen.

Also dokumentieren unsere Workflows, ist doch klar. Aber wie? Einige Möglichkeiten möchte ich in den Tuesday Tipps gern vorstellen. Heute starten wir mit Kommentaren zu Tools und Connections. Vielleicht fragen wir uns dann künftig nicht mehr, was dieses Tool an genau dieser Stelle tut oder welche Daten über eine Connection geliefert werden.

Annotations: Dokumentation für das einzelne Tool

Eine erste Form der Dokumentation wird gewissermaßen automatisch immer mitgeliefert, wenn wir ein Tool auf den Canvas ziehen: die Annotation. Abhängig vom Tool wird hier eine Art Standardtext angezeigt, bei einem Input Data Tool zum Beispiel die Datenquellen (hier der Dateinamen), bei einem Formula Tool die Formel(n), bei längeren Formeln zumindest der erste Teil davon.

Diese Annotations können wir in gewissem Umfang bearbeiten. Über das entsprechende Icon im Configuration-Window des Tools (oder über <F2>) gelangen wir in den entsprechenden Bereich und können nun den Namen des Tools (1) anpassen, entscheiden, ob wir die Annotation anzeigen wollen (2 – Immer/Nie/gemäß Workflow-Einstellung), sie oberhalb des Tools anzeigen (3) und den Text verändern (4).

Entsprechend sieht dann die Darstellung im Workflow aus:

Und auch der Results-Window wird beeinflusst – hier taucht jetzt nämlich der Name des Tools auf, vielleicht ist „Umsatzdaten“ im Vergleich zu „Input Data (1)“ eine etwas „sprechendere“ Darstellung.

Während im Results-Window immer der selbst vergebene Name des Tools angezeigt wird, hängt die Anzeige in der Annotation zusätzlich noch von der Standardeinstellung für den Workflow ab – er wird nur dann angezeigt, wenn bei den Canvas Options für Annotations „Show w/Tool Names“ gewählt ist; wählt man „Show“, werden nur die Annotations angezeigt.

Eine dritte Variante, die für den Workflow gewählt werden kann, wäre noch „Hide“ – in diesem Fall werden alle Annotations, für die „Using Cancas Settings“ eingestellt ist, nicht angezeigt, „Always“ als Einstellung beim Tool hat natürlich die höhere Priorität, diese Annotations werden also angezeigt. 

Comments: Toolübergreifende Kommentare

Wenn wir näher erläutern wollen, welche Aufgabe eine Reihe zusammenhängender Tools hat, helfen uns Annotations nicht mehr weiter, da sie sich ja immer auf ein einzelnes Tool beziehen. Hier können wir auf das Comment Tool zurückgreifen, das bei der Gestaltung erheblich mehr Flexibilität bietet. Wir ziehen das Tool (zu finden in der Toolkategorie „Documentation“) an die entsprechende Position, geben den jeweiligen Kommentar ein und können jetzt auch die Größe anpassen, so dass klar wird, auf welchen Bereich es sich bezieht.

Daneben bietet das Tool noch eine Reihe weiterer Formatierungsmöglichkeiten, wir können Form, Farbe, Schriftart Ausrichtung des Textes wählen und gegebenenfalls sogar noch ein Hintergrundbild hinzufügen.

Natürlich können wir das Comment Tool auch nutzen, um einzelne Tools zu kommentieren! Optisch ist das in jedem Fall ein Gewinn, allerdings im Vergleich zu den Annotations etwas aufwendiger.

Und auch Connections bekommen einen Namen - manchmal ...

Was ist nun mit Connections? Warum sollten die dann auch noch dokumentiert werden? Und wie?  

In manchen Fällen ist es tatsächlich sinnvoll, zusätzlich zu Kommentaren für die entsprechenden Tools auch der Connection einen sprechenden Namen zu geben. Ein gutes Beispiel ist eine Report Map, die von verschiedenen Datenquellen versorgt wird. Woher kommt  hier zum Beispiel welches Spatial Object?

Die Bezeichnung „#1“ sorgt nicht unbedingt für Klarheit – bei zwei Quellen geht das noch, aber wenn es fünf oder sechs sind, wird es doch schwierig, die Übersicht zu behalten.

Wenn wir die Connection selektieren, können wir den Namen ändern und so auch die Inhalte etwas klarer machen:

Damit lässt sich nun einfach nachvollziehen, welche Inhalte die einzelnen Connections liefern; das macht die Zuordnung doch etwas leichter.

Auf Dauer lohnt sich's - habe ich inzwischen gelernt

Wenn man die genannten Dokumentationsmöglichkeiten nutzt, sollte es leichter sein, "Erinnerungslücken" zu schließen. Helfen sollten das besonders bei umfangreichen und komplexen Workflows, aber auch bei der Einarbeitung in fremde Workflows. Bei manchen Workflows wünsche ich mir heute, ich hätte diesen Rat selbst immer befolgt. 

Weitere Tipps Tuesday Beiträge

Dieser Eintrag ist Teil der Tipps Tuesday-Serie, alle Einträge dieser Serie findest du in unserem Index aufgelistet.