Engine Works
Under the hood of Alteryx: tips, tricks and how-tos.
I have recently finished a small project in which I was creating an Alteryx workflow to be handed over to a user with little to no Alteryx experience. One of the key goals here was the focus on documentation, making the workflow easy to understand and hence easy to replicate.
In this blog, I will discuss some key tips when documenting an Alteryx workflow, demonstrating this with a sample documented workflow I created off the back of an Alteryx challenge (challenge number 1).
Why Should I Document My Work?
There are many reasons to document your workflow, even if it's not something that everyone likes doing:
It helps you to keep track of what you've done
When working on a hefty Alteryx workflow, the chances are that you'll be going away and coming back to it over an elongated period of time, during which it can be easy to forget why you've taken certain steps. I definitely find that when I get wrapped up in writing a bunch of formulas, I will have forgotten my exact thought process a couple of days later. By documenting your work as you go along, you allow yourself to quickly pick up work where you left off and track the steps you've made to your workflow. This not only saves you time retracing your steps but also moves us on to the next point that…
...It helps others understand what you've done
Documenting your workflow gives you all the notes you need to quickly explain your workflow to others without having to go into every tool and work out what it is doing. This means you can quickly help others understand what you've done, even if you're not there to explain it to them.
It allows for a quick and easy handover
If you are handing over a well-documented workflow to a client or a colleague they are going to be able to quickly pick it up and work with it, meaning less time wasted explaining tools and a happier bunch of people all around! A poorly documented workflow, however, can render hard work redundant if the new user is unable to understand what has been done, replicate it, or get full use out of it. By documenting your workflow as you go along, you save everyone time when it comes to handing it over, including the time you may have to take to explain everything in depth!
How Should I Document My Work?
Create a Documentation Guide
When documenting a workflow, it can be useful to provide a guide, telling the user how to read the documentation and navigate the workflow. In the example below, I have created a quick documentation guide, providing a title and description of the workflow, whom it was built by, and the last date it was edited. I have then created a key for the color coding of steps I take within the flow so that the user can easily identify what steps have been taken and where. This is a good template for a documentation guide and can be added to as much as needed within the context of your workflow.
I created the documentation guide above by using a series of Comment Boxes (see below) and then formatting them by changing the background colors, text, and text alignment.
Color Code and Label Workflow Steps
A large Alteryx workflow can be overwhelming to look at initially, so breaking it down as best as you can really help other users understand what is going on and not get too lost. By putting the tools in your workflow into Comment Boxes, colored using the color codes in the documentation guide, you allow the user to easily understand the steps/process of the workflow, even if they don't understand what is happening within the tool. You can add text to the comment boxes to provide the context of what is happening in the tool. As you can see in the example below, I have put each tool in a single box and given it a brief descriptive title. You could also put multiple tools within one box which are doing the same thing, e.g., multiple parsing or data cleaning steps.
Add Notes to Explain Formulas
If you are adding tricky formulas to your workflow, or even basic ones, it can be useful to write extra notes explaining what is happening within the Formula tool. For example, if you have written a formula to create a new field, such as creating a field for 'Profit Ratio' out of existing fields, then this is a good chance to explain the formula. Again, I find this extremely useful not just when explaining my work to others but when trying to understand for myself the steps I've taken when coming back to a workflow after a few days or weeks.
Utilize Annotations
This can be useful when putting multiple tools in a Comment Box and allows you to add a little more information to individual tools.
To add an annotation to a tool, select the Annotation tab in the Configuration pane:
Once selected, you can add annotation notes in the 'Annotation' box. These will then show up below your tool, depending on your settings.
Document Data Quality Issues
Data quality is an issue everyone working with data will encounter, but it can often be overlooked by those using the data. Data quality issues can range from missing and unexpected values to duplicate fields. When working with data, it is a good idea to flag up issues as you go along so that when it comes to sharing your work with someone else, you have a ready list of issues to bring up, some of which may not actually be cause for concern, but some of which may be. Alteryx is a great tool for flagging these sorts of issues, and documenting data quality can further help users quickly identify possible data quality issues and resolve them.
I like to filter out rows that have data quality issues using a Filter tool and attach a Browse tool to the filtered data so that I can quickly see which rows have issues and bring this information to someone else to clarify whether or not I should expect to be seeing these figures. As you can see below, I use a different comment box/color, as noted in the documentation guide, to highlight data quality issues.
Final Documented Workflow:
If you follow all the steps listed above whilst building your Alteryx workflow, you should end up with a well-documented workflow that looks something along the lines of this:
Hopefully, this blog has been useful in providing some guidance as to why and how you should document your Alteryx workflows. It is a good habit to get into, and I would highly recommend testing out some of these ideas next time you go into Alteryx!
