Six Alteryx Documentation Best Practices

[mhauler]

You wrote an amazing workflow last year that provided tremendous savings, and you are now being promoted.  As you start to wrap up your work to move onto the new position, you are faced with a few challenges in your Alteryx Workflow that need to be addressed:

• Your workflow needs to be updated and shared with the team.  How has this workflow evolved over the past six months?
• You have less-experienced colleagues who will want to see your workflow and understand how you built it.  Can they decipher why a certain macro was used or why a blob tool was used?
• Your colleagues will now be responsible for carrying out your work.  Do they have enough documentation to keep things running?

This might seem like an easy task, but when you look at your workflow, you are wondering why you developed the workflow, and you even recall there are some tricky actions but cannot recall why.  The quick and easy update is now taking over your time.  You have been asked to rebuild the workflow from scratch to document, but this will take time.  If only there was a better way!

Thankfully, Alteryx Desktop Designer contains multiple tools to help you document your workflows and avoid these tricky situations.  Workflow documentation tools allow users and teams to quickly orient users to new workflows and provide context on the workflow.

So…what are some effortless ways to make sure you avoid this situation?

Simplify and Templatize

Custom Workflow Templates allow for the creation of workflow templates for your organization.  These templates can focus on standardizing the type of data that is required, such as metadata or colors of containers to indicate certain types of logic.  Imagine having a pre-made template that lets users understand documentation requirements when building a new workflow.  Templates are now available in Designer Desktop 2023.2 as a standard feature.

Make it Meta

The Workflow-Configuration window displays the configuration options for a selected tool, connection, or workflow.  The Meta Info tab provides you with information about the workflow and allows you to add information that saves when you save the workflow. 

Whether you choose to name the workflow based on the file name or provide a custom name, the Meta Info tab provides tremendous opportunities to document your workflow.  Add a URL of where the documents are being saved or provide a detailed description of the workflow. 

Annotate for Your Mates

Ever look at a workflow and see things beneath your tools like ‘Sales BBP=Round([Sales]*[GBP],.01)’ and wonder what was going on?  The annotation button allows you to add notes to the project for later reference and provide clarity in your workflow. 

The ‘Annotation’ box allows you to input the new text you wish to see associated with the tool in the document.  This can provide greater clarity on what process is being completed in this workflow.  Imagine seeing the images below when you open a workflow.  Which is easier for you to understand?

Comment for Clarity

One of the easiest ways to document your workflow is to use the comment tool.  While this tool has many hidden powers, it is mostly used in providing others with key information up-front about a workflow, a tool or even inserting an image into the workflow. 

Configuration of the tool allows for changes to shape, font, text color, background color, and text alignment.  The Comment Tool allows for image insertion using the .png, .gif, .bmp, or .jpg file formats. 

Contain Your Enthusiasm….and Workflow

Workflows can be messy, and it is hard for people to make sense of what is happening in your workflow.  It is hard for anyone to see exactly what each tool is doing and how it links to the other tools.  To help make sense of this, we can place groups of tools into separate containers based on several factors (inputs, functions, and outputs). 

Separating the workflow into multiple sections can help users identify the individual portions of the workflow.  Containers allow users to see the relationship between tools and links for greater clarity in complicated processes.  You can name containers to indicate the process steps these tools accomplish in the workflow.  

Another valuable use of containers is the ability to disable the tools inside of a container so they do not run when a workflow is executed.  This can be useful for testing a workflow and documenting the findings using the Comment Tool. 

Whack the Formula

You are almost there!  You made it Meta, annotated for your mates, used comment tools, and put your workflow into a container!  Congratulations, but you still have a nagging feeling that someone is going to look at your expressions (might be in a formula / multi-row / multi-field formula tool) and wonder what you tried to accomplish and why. 

The expression editor in Alteryx already provides tremendous power, but you can extend this power with a simple double whack (//) in the workflow. 

In the example above, we simply added an additional line with an explanation and introduced this comment line with a ‘//’.  The line is interpreted as a comment and displayed in green font.  You can also begin a line with ‘/*’ and end with a ‘*/’ and extend the comment over several lines.  Whether you choose the ‘//’ or “/*’-‘*/”, consistency will be key in your documentation. 

Final Thoughts

While numerous options exist for documenting your workflow, consistency is the key!  Your organization and colleagues will thank you for consistent documentation of workflows and in a consistent manner.  Whether this is part of your organization’s governance strategy or your group/divisions best practices, consistent documentation provides a clearer window into the how and why of your Alteryx workflow.