Alteryx Designer Discussions

Find answers, ask questions, and share expertise about Alteryx Designer.
SOLVED

Workflow Documentation Best Practices

elsastark
8 - Asteroid

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!

8 REPLIES 8
JagdeeshN
12 - Quasar
12 - Quasar

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
20 - Arcturus
20 - Arcturus

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

Alteryx ACE & Top Community Contributor

Chaos reigns within. Repent, reflect and restart. Order shall return.
Please Subscribe to my youTube channel.
elsastark
8 - Asteroid

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

kelly_gilbert
13 - Pulsar

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

kelly_gilbert_1-1648764831962.png

 

  • 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
11 - Bolide

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
7 - Meteor

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
8 - Asteroid

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
6 - Meteoroid

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

Labels