Best Practices on How to use Comments in your workflows

[Michal]

Some time ago, I wrote an article about how to make your workflow look nicer (link). Today, I want to take it forward and focus on comments in your workflows as throughout the time, we have developed our own best practice how to best document and annotate the work.

While there is an option of utilizing containers and annotation of individual tools, commenting is another powerful (yet easy) option how to describe, brand, annotate your work – mainly because it is customizable and you can use it where you want and how you want.

Previously, I have shared an option of adding the background picture (company logo, process diagram etc.) into your comments in workflows, which is surely helpful for branding or explanation of the business logic. When adding the company logo, you can make use of an option of shape “None”, which makes the shape outline invisible and looks better.

Of course, there is much more. At the start of work, I like to add a comment in the top left corner of the canvas containing the workflow/process owner, department or any other details.

However, you can use something much simpler than that – just using various different colour-coding for different purposes. The picture below says it all. If you are fresh in Designer and you automate simple reports or processes, most of it won’t be relevant. If you are an Alteryx pro building large workflows, where multiple users interact with the same thing or when you need to hand over your work to a colleague, you should document your work so that it is not thrown away because it is simply too difficult to understand.

Use comments as much as possible with different background colours for different purposes. In orange, mark and describe some background information about how the workflow is built and why. In green, mark where you expect final users to provide their input manually. In white, you may want to document general comments about process background and what is being done it that part of the workflow. Yellow boxes are highlighters of key elements, key transitions in the entire flow. If your work is not 100% done, you may want to mark possible future changes and improvements so that you can trace it easily next time. You may also produce multiple outputs into different tools or formats. As a best practice, you can highlight them with containers or comments with some additional text.

Feel free to use different colours as well as different types (like model assumptions for modelling purposes etc.). But below is an example of how your workflow may look like.

Sometimes, you can use the comment boxes only to highlight the specific tool. In such case, make sure you place the comment box in the background (right click and send to back) and bring the tool to front.

Feel free to use different shapes as well – this definitely makes workflows look interesting. Rounded comment boxes for marking a results/outputs or key formulas; or rectangles for individual sub-processes or headers. Be creative!

What are your thoughts on this? Do you apply any other rules or methods to document your work? Please share your ideas for others.

Thanks

Michal Lichter & Jan Laznicka

Billigence

[filipgregor1]

Informative & insightful piece gents, thanks for sharing! 

[llytle]

@Michal love this approach.  It's simplistic, but I can see how it will scale out over time.  The upfront work  of documentation definitely makes the project go a lot smoother.  Also, I can see that the practices detailed above would help a team of designers work more effectively together - especially if there is an agreed-upon documentation style in-place at the start of all projects.  Thanks!!