Engine Works

Under the hood of Alteryx: tips, tricks and how-tos.
8 - Asteroid

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!

13 - Pulsar

Hello @Spurs 

Here all the things I use

-containers with colors and direction (from left to right)

-annotations on tools where needed


-the metadata in workflow configuration (easiest to get when parsing but also what is available on server)



-and sometimes the explorer box with a link to the documentation (here on Confluence)


However, contrary to you, I wouldn't put my tools on comment box, I would rather containers that are dynamic.

Best regards,




15 - Aurora
15 - Aurora

Great blog @Spurs,


Just to throw in another opinion to both you and @simonaubert_bd I personally prefer the combination of comment boxes and containers. 

Comment boxes annoy me when you want to select a number of tools, and they in some versions there is a bug where they jump in front of the tools. Containers are nicer for moving stuff around the canvas, and also for disabling - but the caption is too small to easily read. Hence I have coloured containers with a no shape comment box at the bottom of it to get the best of both worlds (with double the overhead 😁)





13 - Pulsar

Thanks for the tips everyone!

6 - Meteoroid

Any tips on exporting the workflow documentation? I know there is a print option for the workflow but, it doesn't seem to work well for larger workflows. I would like to be able to export a high-resolution image (or PDF) of the full workflow that is as clear as the Designer screen. I was going to try to increase the page size to something really large when printing but, there is no custom page size option that I can see in the printer setup. Are there any creative options other than stitching together screenshots to ensure all of the in-workflow documentation is readable? I want to try to avoid redoing documentation work just so non-Alteryx users can have access to the documentation. Thanks!

Designer 2022.1.1.42619 Patch: 5

6 - Meteoroid

Hi, interesting topic. Bits2b developed a documenter tool and came across several of these challenges. We invested quite some time to create a tool to parse a description of any workflow (also the more complex ones). 


Currently available in our tool: General info workflow (type, version Designer, description, constants, chained applications, events), User interface (description and connections to the workflow), Workflow (graphical impression, texttools, tools, tool numbers, icons, configuration, connections from/to), Input files (file names, sheetnames, columns, field types and size), some statistics (tools used, containers (enabled/disabled), also nested containers, containing which tools) and 66 tools with description based on the configuration of the tools ( I can provide a list of tools available if you like).


On top of it, we added the option to load the information to a metadata management repository to combine what we do in Alteryx with the rest of the information world of the customer.




A part of the descriptive result looks like this:




Reach out to me or to Bits2b if you are interested in the documenter tool.


8 - Asteroid

Workflow Admin Manager has a very robust documentation engine for Alteryx workflows saved locally or on Server. Creates Word, PDF, or SVG documents of your workflows, including all metadata, annotation, configurations, a diagram of the workflow, recommendations to make your workflow better, etc.


We have a lot of information posted on the website; you can purchase WAM from Alteryx or Capitalize.

We recently spoke with KPMG at Inspire, and on the following webinar; documentation was a key topic. The webinar discusses and demos documentation at the 27:00 minute mark.



Here's the main site for WAM with short videos of many areas of the platform: https://capitalizeconsulting.com/workflow-admin-manager/

Documentation is the second video as you scroll down.


You can actually submit a workflow (just the XML file zipped) and you'll get a copy of the documentation emailed back to you: https://capitalizeconsulting.com/workflow-admin-manager-wam-audit-report-tool/ Please don't submit anything sensitive. Most workflows aren't but we'd be happy to get an NDA in place if you want to discuss something confidential.


Here's a video of AiDIN + WAM for documentation:



Here are some screenshots of the WAM Audit Doc:

1 Full Diagram.png2 Zoomed Diagram.png3 Tool Category.png4 Recommendations.png5 DB IN and OUT.png6 Tool Config.png