Share Your Governance Best Practices - Documentation

Question

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?

ramesh_neel · Answer

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

KevinWim · Answer

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.

IraWatt · Answer

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.