How do you document workflows?

[jspencerdav]

Workflows is arguably the most powerful feature in HubSpot. Regardless of skill level in HubSpot, users create workflows to automate valuable work.

However, without good documentation, workflows quickly become a black hole of confusion and wasted time trying to figure out why something is happening (or not!). 

The solution? Documentation.

How do you document workflows? Here are the core things I believe every workflow needs documented (what would you add?) :

• Link to workflow
• Change control notes (if workflow is affected by external changes)
• Triggers
• Workflow settings / goal criteria
• Business goal / objective solved by workflow
• Expected outcome(s)
• Properties set
• Dependencies with other workflows
• Internal email / tasks sent
• Core logic defined by each workflow step

And, just as important - how do you keep your workflow documentation up to date?

[Juliaaa]

The easiest way to document your workflows, I believe is based on these 3 action points:

1) Creating a clear and concise naming convention for workflows (e.g., TEAM - OBJECT - FUNCTION)

2) Utilizing the description section of the workflows (e.g., writing the business goal/objective solved, triggers, criteria)

3) And organizing the workflows in specific folders (e.g., depending on teams) and customizing the column view.

@jspencerdav I think you raise a very good point! But I think the RevOps way is exactly to utilize the resources you have to keep HubSpot as the single source of truth - so that information can be easily found and accessible. 

This solution works if you have a pretty standard workflow hierarchy and of course, have set appropriate user permissions that limit the access to the workflows tool to designated HubSpot administrations. Also another point is *education* - making sure that the people responsible for the workflows are entering the data correctly.

 Specific workflowsWorkflow folders

This is nothing innovative of course but can be easily overlooked - What do you think about this solution? 

[nc_3manfactory]

Fully with you @Juliaaa, after experimenting with documenting in Miro, ClickUp, Google Docs and so on the only methodology that has proven to be robust is to apply a clear naming convention and to use the tools within HubSpot itself.

[nc_3manfactory]

Is anyone using Miro or ClickUp's whiteboard feature for documenting workflows in a visual format?

[Jnix284]

I've used Miro to create a workflow visualization before building it, but it seems like that would be very cumbersome to maintain as documentation, depending on how many workflows there are and how complex they are - every update in HubSpot would have to be reflected in Miro, increasing the chance for a discrepancy. I could see this working for simpler workflows and automations, how does it work for you?

[nc_3manfactory]

Exactly the same issue! Miro and the other whiteboard tools are great for
inception and planning but to keep them updated for iterations and changes
just isn't practical. If the HubSpot API allowed export of workflow changes
I'd consider embedding a log in the board or something like that. Ideally
all this would be in HubSpot but I think that is a while away yet.

[Ericsen]

Absolutely agree with this feature being a thing! Hubspot API should definitely created a log in board for you to see your current workflows in a visualization and also allow you to plan additional workflows that are in the pipeline. 

[amber-square2]

Editing my earlier comment - I looked into it and was wrong, you can only get updates if enrollment has significantly changed. 😞 

In case others didn't see - there's a new update that lets you (maybe enterprise only?) subscribe to workflow updates! So if someone makes a change you'll know about it. 

[TErickson_OW]

@jspencerdav I love the template you have. I am stealing it. I use GitMind to map my processes before putting them into action. People love seeing flow charts and GitMind is easy and free to use.

[TracyG]

I searched this whole thread--what template? Where can I find it?

[jspencerdav]

Haha - go for it! Glad you found it useful! For my own projects I like to
use Freeplane for mind mapping out complex hierarchies - but definitely not
as pretty as GitMind!

[ztbyrnes]

I have a slightly different idea that I think would truly support workflow documentation in the same spirit HubSpot typically provides solutions for us. I would like to see something like a record simulator tool to help visualize the string of workflows that would be triggered by a property change. Imagine the same workflow user interface, but instead of seeing actions, it displays the following chain of workflows after certain properties are selected. You would be able to add events like a property change to trigger the next workflow. This functionality would be great for planning a customer journey and for testing processes, and help to see around corners where unexpected workflows may be running. Would anybody else benefit from a tool like this?

[Jnix284]

@jspencerdav are you using google sheets, excel, or some other application to track your documentation for workflows? A quick google search for "HubSpot Workflow Documentation Template" resulted in 0 relevant results (hello, SEO opportunity)... lots of documentation for workflows, just nothing about documenting a process. Also tried "HubSpot Workflow Process Documentation Template" - anyway, I was just curious what type of format you use for your documentation.

[jspencerdav]

Oh, yes blog post is pending! 🙂 We are using Google Docs for the creation... tracking changes is a whole 'nuther beast. The Google Doc includes a document-specific style guide which helps keep the process documentation itself a bit cleaner. 

[HBirtcher]

I think this is a great idea. I would love if HubSpot had a notes section in the workflow for us to do alot of this documentation. Then the ability to export the workflow list with the notes. In our system we have myself (the CRM Admin) and an external marketing agency that have the ability to make workflows. It would be great if we could see the thought process, goal, etc when reviewing the others creations. 

[amber-square2]

There is a Comment section now (in the bar on the right) but I don't know that anyone knows to look there! 

[JenBergren]

I was going to say, you can add comments to each action in the workflow, in the visual area itself and then refer to them in the sidebar yes, though no comments can be added to the trigger.

It is progress anyways over no notes inside workflows! 🙂

[HBirtcher]

AHHH This is fantastic! Such an awesome addition. 

[MrBean]

This is great! Curious though, what do you mean by "goal criteria"?

Also, to your last question-- maybe a workflow that assigns a task to whoever creates that workflow asking that they document it. Or an email questionaire (say a google survey) that is automatically sent to the user who changes/updates the workflow. 

Currently this is not something we are doing... but seems like a must-have process as we scale.

Very thoughtful post... i'm curious what other ideas people may have

[jspencerdav]

Hey, @MrBean - good question! That is simply the Goal set in the workflow settings. In a recent itteration of this documentation outline, I've separated 'Settings' and 'Workflow Goal' as separate bullets.

[amber-square2]

Goal criteria helps gauge success: https://knowledge.hubspot.com/workflows/use-goals-in-contact-based-workflows

And for Contact workflows you can use that to unenroll contacts from a workflow when they meet a set goal. 

I think a big piece of keeping documentation up to date is being able to lock down permissions for editing workflows...seems like a lot of users have Super Admin access and mess with things they shouldn't. 🙂 I would love to start seeing HubSpot Super Admin seen on the level of Salesforce Admin - where a process needs to be followed to request a change from the designated person, who would then know to document their changes.