One of the great advantages of working with Alteryx is the speed with which you can develop a workflow. When I am doing this, I sometimes forget to work on the documentation of the workflow in the meantime. However, your colleagues or future me will be very grateful when you do. When in the (distant) future the workflow needs to be looked at again, it is nice to be able to quickly understand what it actually does. For this reason, I am writing a short blog with some tips that will make documenting your Alteryx workflows easier.
Tool Containers
Using tool containers is a convenient way to keep your workflow organized. I like to bundle tools together that take on a particular process of the workflow. In the example below, you can see multiple containers:
- The first container indicates that this is where data "flows into" the workflow
- The second container contains tools that clean the data
- The third container contains tools that aggregate the data
- The fourth container brings two streams of workflow back together
Example of using tool containers
You can give titles to containers to indicate the purpose of the tools inside. What is also useful is to use colors to indicate what type of transformation takes place within the container. I use:
Green for input and output of data,
blue for data edits,
orange for aggregations or changes to the structure of the data
and purple for bundling different flows in the workflow.
Some choose to use comment tools to bundle tools, but I personally like tool containers better. The advantage of tool containers is that you can minimize them (arrow at top right) or even close them (radio button at top left).
Comment tools
Even though I prefer to use tool containers rather than comment tools, it is useful to use comment tools. When you want to provide an explanation of a particular piece of the workflow, it's easy to add a comment tool and then put this explanation in here.
Annotations
Another tip I can give you to document your Alteryx workflow is to use annotations. It is possible to add an annotation to any tool. Some tools annotate automatically, think of the formula tool, and some do not. I use annotations of tools in order to visualize the purpose of the tool itself. Often I overwrite the default annotations because the default annotations are quite extensive (formula tool) or redundant (sort tool). Customizing the annotation is done by clicking on a tool and then selecting the label icon in the configuration screen.
Tool names
While developing a workflow, it is important to keep an eye on the workflow log. Any errors or warnings will appear here. When you do not change the tool names, they will have names like Filter (4) or Summarize (23). However, when you have multiple tools of the same type in your workflow it will no longer be clear which tool it is. By renaming the tool you can make reading the workflow log easier. Customizing the name is done in the same screen as the tool annotations, but in a slightly different place:
Below is an example of the workflow log with regular tool names and custom tool names:
Standard names
Custom names
Conclusion
These are the ways I personally use to document Alteryx workflows. I hope for you (and your colleagues) that you will start using them too. If you are looking for examples of how to document a Tableau dashboard look here.
If you want to see a list of all our blogs you can click here.