Workflow Documentation Best Practices

[elsastark]

Hi Community!

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!

[JagdeeshN]

Hi @elsastark ,

The below document covers many great best practices. Hope this helps.

https://community.alteryx.com/pvsmt99345/attachments/pvsmt99345/inspire-17/265/1/Alteryx%20-%2024%20...

Best,

Jagdeesh

[MarqueeCrew · Accepted solution]

Listen to the ACEs!  Here's a link to what happens when you ask a simple question about best practices:

https://community.alteryx.com/t5/General-Discussions/Catch-the-ACEs-at-Happy-Hour-and-this-is-what-y...

Cheers,

Mark

[elsastark]

Thank you @JagdeeshN and @MarqueeCrew - appreciate the helpful links!

[kelly_gilbert · Accepted solution]

@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!

Key takeaways:

• 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-thread here.

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.

[allwynthomas24]

Hey @kelly_gilbert,

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.

Regards.

[willhaye]

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.

[elsastark]

Thank you @kelly_gilbert - super helpful and love the Start Here folder idea! We were wondering how we make sure people have an easy way to find the work we put together. 

[Chris6]

Hello Elsastark

I am currently reviewing a document for client, they have made reference to the following blog as recommended guidelines for documenting Alteryx workflows.

Documentation Best Practices with Alteryx - The Information Lab

[esoden]

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, annotations, 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.

https://capitalizeconsulting.com/webinar/alteryx-users-streamline-your-external-audit-with-wam-with-...

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:

https://www.linkedin.com/posts/eric-soden_documentation-is-every-developersdream-activity-7095003292...

Here are some screenshots of the WAM Audit Doc: