As an Alteryx developer/reviewer, understanding the role of documentation is very important in our jobs. If you’ve ever spent hours trying to understand a workflow someone built, you know how important good documentation can be. In Alteryx Designer, documentation is even more crucial because workflows can quickly become complex.
Let’s explore how to properly document your Alteryx workflows while closely examining their future performance and durability. We will also explore the next step: setting up templates for future users to use.
Maybe you are an experienced developer trying to implement a COE or just new to Alteryx. The aim here isn’t just to follow best practices but to find a practical way to make documentation a helpful, easy part of your workflow process. Whether you’re an Alteryx pro or new to the tool, these steps should help you create workflows that make sense to anyone who reads them, that being someone else or even you down the line.
Whenever we discuss documentation, we often return to a personal example. After analyzing a specific workflow, I complained about the lack of documentation for such a complex workflow. The issue? I was a developer a few years ago. As your skills progress, sometimes even the workflows you develop won’t make sense if enough time passes.
The solution for these problems? Documentation and templates. The supplement to such a solution is to offer everyone the structure to make a workflow more readable. Nowadays, Alteryx offers this as a pre-built option. Before, we had to share the logic through whatever method was available within the company, but now we can do this from the Alteryx Designer File menu.
Why Document Your Workflows in the First Place?
We all know documentation is important, but let’s be honest; many of us put it off, and there is always tomorrow to do documentation. It is not needed right now, and no one else is using it, right? Well, yes, until it is too late, it becomes a lot to do. It’s tempting to skip this step because it doesn’t seem as urgent.
However, documenting workflows brings real benefits and makes things easier for everyone involved. Here are some thoughts we have had while developing and reviewing other workflows.
Clarity: If you’ve ever struggled to determine what a specific tool does, you know the value of clear documentation. The reason why the workflow logic was built that way is not always 100% clear. This can be applied to a singular tool or multiple tools.
Faster Maintenance: When workflows are documented well, updating or troubleshooting becomes much easier. Documenting and developing with a modular approach allows much cleaner and faster maintenance.
Knowledge Sharing: If someone else needs to use or edit your workflow, documentation saves them and you a lot of headaches. Rarely do people truly understand 100% of what you explain to them. Help them document it!
Compliance and Auditing: Some projects need to follow specific rules, and documentation helps keep everything aligned and consistent. Sox Compliance is really important, and these workflows must be properly documented and managed.
Key Parts of Workflow Documentation
A well-documented Alteryx workflow should have several important components. Here’s what to include:
1. Workflow Summary
Start with a quick overview. This summary should explain the workflow’s purpose, the problem it addresses, and what outputs it generates. The goal here is to give anyone who opens the workflow a clear idea of what it’s supposed to do. As someone else, “If I read this, do I understand what this is for, or do I need prior knowledge of the process?”
Example summary:
“This workflow cleans and organizes quarterly sales data for the North region. It removes duplicates, standardizes product names, and aggregates sales by category. The output is a formatted dataset ready for reporting in Tableau and used by the sales team for their monthly review meeting.”
2. Input and Output Details
List out the data sources and outputs, along with some specifics like:
Inputs: Names of files or tables, formats (e.g., CSV, Excel, database), and how often the data updates. You don’t have to list everything, but what are the non-obvious aspects of your input datasets? Do they need access to the Sharepoint folder? Is it a specific Snowflake connection? Etc…
Outputs: Final file or table names, format, destination (e.g., saved in a specific folder or a database), and what the output is used for. Are these outputs being used on a separate future process? Or is it a standalone solution? Add links, if helpful, to the Tableau Dashboard with which the workflow is associated.
This information is especially helpful if you—or someone else—need to troubleshoot or update the workflow later. We want to avoid breaking any existing processes. Clean documentation lets anyone understand what is happening with the data products being produced.
3. Annotations for Key Tools
Alteryx lets you add annotations to each tool. This is a simple but powerful way to explain what each tool is doing. While adding annotations to all tools may be a good practice. It is a lot of work. What we recommend is identifying the key tools. Maybe you are filtering data in a way that needs to be highlighted, or where you are creating all the metric calculations using a formula tool. Good annotations can make a workflow self-explanatory.
For each key tool, include the purpose – a brief explanation of why this tool is in the workflow and why someone needs to understand what is going on there. When you annotate the key tools, they stick out, and anyone else can quickly mentally map out what is going on.
For example, if you’re using a Filter tool to remove low-value transactions, you could write:
“Filter out transactions with a sales value below $50. These small transactions are not relevant for this analysis.”
4. Explaining Complex Transformations
Some workflows have complex parts, where several tools work together to create an important transformation. In these cases, you’ll want to provide a more detailed explanation, either as annotations or comment boxes. This is where you explain any calculations, logic, or decisions behind the workflow steps.
Seeing a container like this one may send the person down a rabbit hole, trying to figure out everything that is going on.
A quick and simple comment like “Reading all .txt files, creating a JSON structure, filtering out by each group that needed to be treated separately (look at each filter tool) and then combining it all into a tabular format” would allow anyone to truly understand at a high level what we are trying to accomplish within this section of the workflow.
Alteryx’s Built-In Documentation Features
Annotations – Annotations are easy to add by right-clicking on a tool and selecting Annotation. Keep annotations short and direct—just enough for someone to understand what’s happening. We like to enable only specific key tools with annotations to avoid overwhelming the reader.
Containers – Containers let you group related tools, which makes the workflow easier to read. You can name containers to describe what each group does, such as Data Import, Data Cleaning, or Aggregation. Containers also let you collapse sections, which reduces clutter. Create a modular approach to your workflow using containers.
Comments – Add comments to specific areas in the workflow where further explanation is needed. Use this as the high level documentation to a module in your modular development.
Tool Labels – Renaming tools to something descriptive (instead of the default names) improves readability. Instead of Filter 2, try Filter – Remove Low Sales Values.
Building a Workflow Template in Alteryx
Templates are a great way to save time and ensure consistency across multiple workflows. Share this with other users. Follow the same idea and implement this enterprise-wide. This way, anyone can read and adjust any workflow with the certainty that nothing will break, no matter who developed it. Here’s a simple approach to creating a reusable template.
Conceptually, all workflows will be different, so their documentation is unique. A template is not to be followed by everyone for everything; it is more of an advice than a law. Allow flexibility and explain the different approaches someone can take.
Using some placeholder tools, describe a simple workflow. You can even use the examples provided by Alteryx. Document this workflow as if you developed it to be shared with others. Future users of this template shall see how a workflow can be documented and follow the same idea but not necessarily the same steps. Documentation shouldn’t be a hassle to anyone, the developer or the future user.
Templates are interesting because you can create workflows, apps, or macros. Either asset type has its specific features. A template can be helpful:
Workflows – Overall documentation and organization for all the workflows
Apps – Interface builder allows you to set visual guidelines for how Apps should look at your company.
Macros – Although they can be complex, creating a template allows you to establish the proper documentation and macro interface for other developers.
To create a template, open a blank workflow or a workflow you deem good enough to be used as an example, what you believe would be good examples at your company. Once you are done, hit Save As > Template. The template file extension will be different depending on the type of workflow you have on your Workflow Settings. Here is an example of what the Save as a Template window looks like.
Share this template with all the necessary users. It is saved in the following folder:
C:\Users\{username}\AppData\Local\Alteryx\Templates
To open it, click File > Template and select your desired template.
Conclusion
Proper documentation and the use of templates can make a significant difference in how easy it is to maintain, share, and understand Alteryx workflows. Documenting your workflows carefully and creating reusable templates will save time and reduce frustration in the long run. Try to avoid leaving it as the last-to-do item. Document your workflow throughout the development process and update it as necessary. Avoiding the burden of the “just need to document it” allows you to create a good product with the right focus.
We hope this guide has helped you understand the importance of documenting Alteryx workflows, the key components to include in your documentation, and the steps to create a useful workflow template. Remember, a little effort in documentation now can make a big difference down the road.
Start implementing these documentation strategies today to create streamlined, accessible Alteryx workflows. Have questions? Reach out, we’re here to help!
