Do you have an organizational or personal way of documenting workflows?

[LeahK]

For those of you who may have missed last weeks post, we're starting a weekly Q&A Thread, called the Thursday Thought. Every week we pose a question to the community and invite members to share their experience. Even if you don't have an answer/solution to the question, you are still welcome and encouraged to participate. Think ahead... What problems could you avoid by having these processes in place?

Question:

What processes, if any, have you put in place to make workflows more understandable, shareable, and traceable?

[LeahK]

@Aguisande, that's definitely the plan :) The combination of responses we've received here, will make an excellent asset!

[Philip]

We've been working to create some standard practices so that workflows and documentation are similar across several developers. Some key things:

1. A general layout system where we group tools into three Tool Container categories: Input (with a specific color), Transformations (with a different specific color), and Output (with a specific color). This was done for ETL work. In the future, we'll probably add some additional categories, such as analysis. Within these containers, the workflow can be grouped and documented further.

2. Have standardized annotation text template. Why? Because it reduces the amount of thought needed to annotate a took, removing one more barrier to getting everybody to document processes. They don't always fit, but most of the time they are great jumping off points. These are just starting to be implemented and tested, so may change.

Annotation guidelines by tool type. Do not use the tool name in the descriptive annotation. Use short phrases in present tense, rather than complete sentences. Where possible, descriptions should simply contain a verb and field name(s).

Tool type	Annotation contents	Example(s)
Filter	“Remove” + record description OR “Retain” + record description	Remove blank records Retain records with data Retain records with PIN = Premises
Filter*	“If <field, condition>…” (followed by “…Then/Else…” on subsequent tools)	If Collection State has no data…
Join	"Match on" + field names used to join tables (or descriptive names for fields, if field names are not intuitive)	Match on Order ID
Summarize	Brief description of what is achieved by summary	Remove duplicates
Formula	Brief description of what is achieved by formula	Convert Test Code to uppercase Trim whitespace Set Test Code to blank
Input Data/Text, Connect In-DB	Filename (if applicable): Fields used from this data source (or descriptive names for fields, if field names are not intuitive), comma-separated	PIN, Submission Reason location.csv: Location ID, Address
Output Data	Filename (if applicable), automatically populated by Alteryx	Output.xls Table=‘Sheet1$’
Message	“Record changes to log”	Record changes to log

[StephaneP]

Hello,

I am a little bit late in the show but I think it is worth mentioning those 3 articles I have just posted on the community about "How to make your workflow impactful?". There is a slight nuance in the sense that those are not rules to increase maintenance but rules to increase 1st good impression and understandability. But it is right in the target of documenting.

Example: Before/after

Part 1: Prepare yourself and your audience

https://community.alteryx.com/t5/Engine-Works/Make-Your-Workflow-Visually-Impactful-Part-1-Your-Prep...

Part 2: Prepare your workflow

https://community.alteryx.com/t5/Engine-Works/Make-Your-Workflow-Visually-Impactful-Part-2-Your-Work...

Part 3: Enrich with visual effects

https://community.alteryx.com/t5/Engine-Works/Make-Your-Workflow-Visually-Impactful-Part-3-Visual-Ef...

Hope it helps.

Enjoy & share