Share Your Governance Best Practices - Documentation

[MeganDibble]

Hello Community!

For today's Thursday Thought, I would like to keep the discussion about governance going. Governance is an important topic for many organizations as they want to have processes controlled and minimize their risk. 

When working with Alteryx, one way to increase governance of your processes/workflows is through documentation! If you haven't already, I encourage you to check out our second Vacation Proofing Your Workflows webinar content, which is all about documentation. 

And now let's hear from you:

How do you document your workflows, and what do you see as best practices?

[TheOC]

Hey Megan,
You're right - governance and documentation is essential, especially when working with different team members (or clients).
I like to document workflows I create using a workflow template to make it as easy as possible for another user to follow - especially when we consider 'bus theory'.

I wrote a blog not too long ago on this - unfortunately you cannot set it up to open each time you open Designer anymore, but it can still be utilised as a manual open:
https://community.alteryx.com/t5/Alteryx-Designer-Discussions/How-To-Create-a-Template-Workflow-That... 

[DataNath]

Fairly similar to @TheOC (and very cool to see how you managed to force templates at startup, shame it stopped working!) but with different colours! At TIL, @BenMoss' blog on documentation is still going strong and most of us tend to follow this: https://www.theinformationlab.co.uk/2019/02/14/documentation-best-practices-with-alteryx/ - just throw in a couple extra colours if you start playing around with anything not covered by the core sections. As an addition to breaking out the workflow like this, whenever I've built anything important, I often like to write up a supplemental document just giving an overview of key steps/calculations and such as well. Especially for non-technical stakeholders, I've found providing an 'english sentence' explanation of things is often appreciated.

[IraWatt]

Not sure if this has already been mentioned but the Auto Documentation - Alteryx Community project is very cool. It creates a pdf doc based of the workflow file automatically. Definitely worth looking at for a documentation starter template.  

[KevinWim]

In addition to using "process colors" as described here, I will also:

• group larger processes using colored comment boxes with large titles
• utilize the tool annotations to better describe what's happening in plain English
• name the connector lines when it provides additional clarity (defaults are #1, #2, etc.)

(Tangentially related to documentation)

Finally, for larger workflows where I need to make sure I don't lose data records in the process, I will add a record count data checkpoint at the end of the workflow for each of my inputs. This looks like a "data in" stream where I do a unique count on a certain field and similarly do a "data out" stream in the same manner. This not only helps me when I am building the workflow to ensure I am not missing anything along the way, but it gives other users of my workflow confidence that the workflow is operating as designed.

[ramesh_neel]

Yeah agree with most of you. Template is the way to ensure consistency across all your workflows , though I do not use much of color coding , what I ensure is that every workflow has a section that tells in detail what exactly is the purpose of the workflow and the business problem it solves . We also include the business contact details and a link to a detailed documentation of the workflow in any external systems like JIRA or Confluence . The URL section under the Meta Info tab of the workflow is an excellent way to link your workflows to its documentation. (Can also be used to link to any visualization tools if the workflow is used to prep data for the viz )  .  I also like to add comments to complex formulas ! I

I also have a blog on some of the above points written not too long ago  - https://community.alteryx.com/t5/Engine-Works/10-Alteryx-Tips-and-Best-Practices/ba-p/976036