This site uses different types of cookies, including analytics and functional cookies (its own and from other sites). To change your cookie settings or find out more, click here. If you continue browsing our website, you accept these cookies.
We are currently building out guidelines, tips, and tricks for workflow documentation within our organization. Our hope is this helps not only the Alteryx developers but any consumers of their workflows that need to understand the logic within Designer without having to fully know Alteryx.
Ideally, we want our workflows to follow a similar documentation style. Some of the things we are covering are:
Color Coding Containers (with a legend at the top) - things like Inputs, Outputs, Error Handling, Reporting, etc.
Adding Comment Boxes for anything that needs further explanation
Renaming any tools that aren't as clear on what they are accomplishing
Adding a container with general workflow information at the top of the workflow
Updating workflow metadata, especially to link to any further documentation there may be
Being super clear on which "tools" are actually macros built by the user - as that isn't always obvious to other people
Any other best practices you have found that could be helpful to include? Also, currently our thinking is we will share this with a document outlining how to do these things but also providing them with a template workflow they can copy over and look at but happy to learn about other ways you may have done this!
@elsastark - attached is the deck from a talk I gave at the Atlanta Alteryx User Group a while back - there are SO MANY threads/blog posts on workflow documentation, I wanted to assemble the important ideas in one place. I think your list above covers most of what I typically use, though!
Use documentation tools to quickly orient the user to the workflow
Annotations, comments, containers, connection labels, formula comments
Use documentation to explain (generally) what the workflow does
Use documentation to add context (why)
Use a consistent workflow template
Save it to your private gallery
Save it to your Start Here folder to have it open automatically
Use meta info when sharing workflows
Here's an example of our standard workflow template:
The Color Samples container includes a container and a comment in each color, so the user can copy and paste. We based our colors on The Information Lab's template, except we adjusted them a bit to align with our corporate visual identity system.
The General Workflow Checklist container has some pre-handoff/pre-save to the Gallery reminders, such as:
Add the Meta Info
Add a workflow event After Run With Errors to email yourself (or team mailbox) when a workflow fails
Remove unnecessary rows/cols as early as possible in the workflow
Remove or disable Browse tools
Use workflow constants where possible (instead of hard-coding contstants)
Use Test tools to check for issues (e.g. records falling out of a Join) and stop the workflow if necessary
In apps or macros with interface tools, use the Error Message tool to validate the user's input
Use Message tools to pass messages to the Results window (these messages will appear in the workflow results in the gallery)
If you want even more options, @willhaye started what I call the documentation mega-threadhere.
And finally, adding the standard template to the Start Here folder has been life changing! The template is always open when Alteryx opens, so there is almost no friction to using the template whenever you start a new workflow.
Thanks for that detailed explanation & all the attached resources. Never knew so much of detailed explanation is needed as I have not got to work on such projects. Surely will try to learn and implement documentation.
Thanks for the shout out, @kelly_gilbert ! Appreciate you sharing your work as well. I think the very flexibility of the tool leads to disconnect problems when you try to scale a solution to many Alteryx analysts. Getting aligned so that everyone is working from the same basic structure helps you get to the problem at hand faster.