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 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 yourself 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 round! 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, who 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 helps 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 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 Captions

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 a caption 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 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 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!