Documentation: Tips on Creating Helpful Documentation

Flow Documentation Month is here on The Flow Architect. Over the next five weeks we’ll be covering a variety of sub-topics relating to the overall topic of Flow documentation. There will be a posting going live each Thursday night (UK time) for the next 5 weeks. Today’s post will be the first post in this 5 week series, this week’s edition will cover my tips for creating helpful documentation.

A Brief Reminder of What’s Coming This Month

Over the course of March 2023, I will be releasing the five posts shown below, all on topics related to Flow Documentation.

Graphic showing the release date of each post in the currently ongoing Flow Documentation Month blog post series.

Today mark’s the first post in the series. We will be looking at the topic of Tips on Creating Helpful Documentation. The remainder of the series will come out each Thursday for the remainder of the month. All posts will go live at approximately 6pm (UK time, GMT).

The remaining posts in the series will be as follows:

• Thursday 9 March – What Can You Use Inside Salesforce?
• Thursday 16 March – The Flow Docs You Need Most in Your Life
• Thursday 23 March – Let’s Talk About Naming Conventions
• Thursday 30 March – Creating a Flow Documentation Strategy

I will also be creating a new resources page which should go live sometime during the month of March which will hold a number of resources to help you in your Flow efforts. I will share on social media when this page goes live so you can find it and bookmark it.

But now, that we’ve recapped what’s happening in this series, let’s talk about today’s topic.

What We Will Cover in this Post

As you will tell by the title, in this post we’re going to be talking about how you can create helpful documentation for your users as it relates to the declarative automation that you build in Flow. Here I will share my personal tips on what you should do in order to achieve this. Please note, that I won’t be specifically focusing on the documents I would encourage you create to document your Flows (that is coming in week 3 of this series as noted above). Nor will I be covering things like what you can use in Salesforce to help your documentation efforts (week 2), naming conventions (week 4), or how to carve out a good Flow Documentation strategy (week 5). This week is solely about my tips for creating good and helpful documentation for you as the Admin, and your users.

For this subject, I have 4 tips that I want to offer. These tips do cover quite a bit of ground, however, I feel that these 4 tips cover the biggest talking points when it comes to documenting you Flows. So we’ll cover each of those 4 tips in this post. If you have your own tips to share, please do feel free to share them in the comments below. The tips I’ll be sharing are my personal thoughts on the topic, I do think these are good tips (that’s why I’m sharing them), but you may have tips that are helpful to Admins as well, you may even have tips that are better than mine, so why not share your documentation tips to help out other Awesome Admins.

So without further ado, let’s get into my 4 tips for creating helpful Flow Documentation:

My 4 Tips for Creating Helpful Documentation for You and Your Users

Below are my four top tips for creating helpful Flow Documentation. This isn’t necessarily an exhaustive list of tips I could offer. Rather, these are the four umbrella tips that I think all the other tips I would offer fall into. As noted before, if you have your own tips for creating helpful Flow Documentation, I would love to hear that. So why not share your tips in the comments below?

#1: Don’t Overcomplicate Things

The first tip on my list is to not overcomplicate things. This may sound like an over-simplistic point when you first read it. But hear me out. In my experience, documentation that goes into every little minor detail in the key areas of documentation often don’t get read by end users, and can easily end up in not being read. We can also easily focus too much on the technical side of what we end up documenting that our documentation misses out on what is arguably the more important subjects within our documentation. Why we need what we’re documenting, who it serves, and what problems it solves. When it comes to Flow, I think we can very easily get into the weeds too much in how we document what we’re building. After all, we have to think about things like variables, elements, trigger order, order of execution, API versions, external connections and a whole host of other things as we build our Flows. Now, I do think that there is a place for documenting all of those things (and everything else in a Flow), when it comes to documentation for our users, in my experience we can get too technical in it and create a barrier to entry to reading and being able to understand our documentation. I’ll talk about this a bit more in week 3, but I do think there is a place to document things like the variables we build in our Flows (among other things), I’m just not convinced that falls within the main part of the document.

So what I’m encouraging here is a focus on simplicity to explain complexity. What does that mean exactly? Well, obviously Flows are somewhat complex in nature, but how we document them doesn’t have to be. We can do a good job of explaining the pieces of complex automation that we build in a way that is digestible and easy to understand for everyone, technical and non-technical.

So rather than documenting every minute detail of a Flow in the documentation, I am recommend that admins focus on 3 things:

• Why is the automation needed?
• What business problem does it solve?
• What does the automation do?

If you can explain each of these areas well within your documentation, I think you’re on the right track honestly. I do think we should document each element within our Flows for sure, but I don’t think we necessarily need to write down everything little thing about it. We just need to cover the key things that the user needs to know in order to understand what the element does within the wider view of the automation. Veering on the side of clarity and simplicity will help your users understand your automation.

#2: Use Images to Snapshot Your Canvas and Elements

Next, images are a massive help when it comes to documenting anything in Salesforce … including Flows. Many people will find it easier to understand your documentation if it includes screenshots of the items you are covering in that particular section of the document. My personal recommendation is to provide a screenshot of the entire canvas and add that in your intro section of the document, and then to screenshot each individual element of your Flow so that you can show what each element includes in it.

There are different tools you can use to help with that, personally I use a Chrome Extension called GoFullPage. GoFullPage allows you to screengrab an entire webpage and download it as a PDF or a PNG. There is a pro version that allows you to edit the image, but I usually just download the full image and take it into Photoshop to do any editing on it I need. You can easily do the same with tools like Canva or Photopea. Both of which are free design tools you can access online (Photopea is pretty just Photoshop).

Providing screenshots where it makes sense to is something that your users will really benefit from when it comes to them being able to understand your Flows. As it will give them a means of visually seeing what is included in your declarative automation. It would be prudent to include textual explanations of what’s being shared via images to further explain the items being shown.

#3: Keep Labels and Descriptions Clear, Concise, and (Ideally) Short

Next, let’s talk about things like labels and descriptions. In my view, the best of the best of Flow Builders will always provide good descriptions in the Flow settings and for each item they create that holds a description. Now, I do think that descriptions can be added later or that if you are building a Flow live in a presentation that it’s OK to not include descriptions (after all, if you’re doing a live build in a 20-30 talk you will save time by not including descriptions), but for Flows that are going to be deployed from a Sandbox into a Production org … descriptions are an absolute MUST!!! That being said, I do think that there are certain things we can do to make our descriptions stick the landing … in this section we’ll talk about that as well as my thoughts on labels in Flows.

First, Let’s Talk about Labels in Our Flows

When it comes to labels in Flows my views have changed a little over the last year or so. Honestly, this is mainly because of Screen Flows in Slack, I’ll talk more on that in just a second. But as I say, my views have changed on the subject a little in the last year or so.

So here’s my brief thoughts on how we should build out our Flow labels:

1. Keep them short, ideally no longer than 25-30 characters in length.
My current view is that Flow labels should be relatively short, ideally around 25-30 characters in length. This is because of what I term as visual limits. By a visual limit, what I mean is the number of characters that can be seen for an item before it is no longer fully visible in wherever the item in question is being displayed. For Flow Labels, this again has largely come from Slack, in my experience of using Screen Flows in Slack there is a cutoff of around 30 characters for the main label of your label when a Screen Flow is displayed in Slacks popup modal for Screen Flows. We also see this issue rear it’s head for labels on the Flow canvas, at a certain point the label will not be entirely visible (this is particular the case for outcomes in decision elements). My view, as simple as it sounds, is that your labels should be entirely visible on your Flow canvas and in Slack when you launch your Screen Flows.

N.B. I don’t think the length of labels for resources have to be as short as labels for elements and the main Flow label as they aren’t displayed in ways that the title will be obscured from view as resources are located in the Toolbox of your Flow in Flow Builder.

2. Make Them Descriptive … Tell Your Users What The Item Will Do
My second thing about labels is that they should be descriptive. I understand that might sound a little odd considering what I just said about the length of your labels. However, I think you can easily make your labels descriptive as well as short. What I mean when I say descriptive is that it should clearly describe what that item is doing … this is particular the case for elements. I don’t think it’s helpful to have say an Update Element called say, MyRule (if you know, you know) because that doesn’t really say what it does. Rather, a label should explain what the thing is doing, again for something like an Update Element, calling it something like Update Contact is going to be far more helpful to a user. Obviously if you have multiple elements doing similar jobs, then you need to consider how clearly differentiate between each item as having multiple labels that say the same thing isn’t too helpful either. I would also recommend that when you build out your labels you have a consistent language around what that item is, again this is particularly true for elements, so for me when I add an Update Element in a Flow, I always have the label be Update … (obviously the … denotes whatever the item is I am updating). When it comes to resources, I don’t think you need to include the type of resource it is in the label necessarily (I think that can be handled in the API name), but the label should still be descriptive. For example, if you include a formula to set say the end date of a Campaign, then setting the label to be something like Campaign End Date is more than ideal (for that I would set the API name to be formulaCampaignEndDate or Formula_Campaign_End_Date).

What About Those Description Fields?

OK, now for description fields. I think descriptions are a little different than labels, but I do think the two principles above apply to some degree. Obviously, a description element should actually describe whatever that description is tied to, it’s no good having a description that doesn’t actually tell the user or an Admin what that item actually does within the Flow. We need to have good and helpful descriptions within our Flows. I have my own thoughts on what a good description looks like (I’ll share that below), but before I share an example of what I think is a good description, let’s talk a little about the length. For me, I think a good description differs slightly between the main description of the Flow and a description for an element or a resource (with slight differences).

First, the description for the Flow overall. The description element here is found in the basic details of a Flow. My view for this description field is that it should give a brief and concise overview of the Flow. One that describes the purpose of that piece of automation overall. This isn’t displayed on the canvas anyway, so I don’t think length is too much of an issue. However, it should be kept up-to-date, I have seen these description fields not get updated when changes are made to a Flow with those changes resulting in confusion and the description no longer being accurate or helpful. I do think a basic change log in the description is helpful to have, but I think if it isn’t going to be updated in the Flow then it is better to have that in an external source. So the main Flow description can be longer, and it should give a concise and accurate overview of what the purpose of the automation is.

Second, description fields for resources. I’ll talk about this before descriptions for elements as there is some slight differences between them now due to the inclusion of description bubbles on the canvas (a new addition for Spring ’23). Like with the overall Flow description, I think that descriptions for resources can be whatever length you need. These descriptions are not displayed on the Flow canvas, so length isn’t as much of a factor. That being said they should still be descriptive. I’m not saying description fields have to be an essay, but having a description that actually conveys what the resource is the way to go in my book. For example, if the resource is a formula (let’s stick with my example of the Campaign End Date), a good simple description for that would be something like, this formula calculates the end date of a campaign by adding X number of days to the current date to determine what date the campaign should end on. You could probably write something a little better than that to be honest, but what you will hopefully notice there is that the example I gave for that description explained what the formula is doing, it covered the fact that the formula would add X number of days (obviously I want change the X to a number ideally) to the current date in order to calculate the end date of the Campaign. That kind of description is brief, concise and it tells the user what the formula does. In my mind that is a good and helpful description that you can easily use within a resource inside of the Flows that you build in your org.

Thirdly (and finally) we have descriptions for elements. In my mind this is a little different than the other two because of the new addition of description bubbles in Flow Builder. For me, description bubbles are an absolute game changer, but they do bring in some potential need to change how we write out our description fields for elements (maybe). Similar to what I mentioned for Screen Flows in Slack, description bubbles also have a visual limit. The visual limit for description bubbles is far more sizable than is the case for labels. Honestly, I haven’t found an exact character count for the visual limit as it depends on the screen that you use. However, what I can say is that after a certain point, your description bubble will stretch beyond the boundaries of the canvas view and you will begin to miss text in those description bubbles. So while you can totally include descriptions that are a good length, my recommendation would be to not include much more than a single short paragraph to avoid having your description not be visible on the canvas. So shorter, but still descriptive is the right balance in my eyes. I’d be interested to hear what you think.

Now, for a good example of an element description, I said that I would share one. So here is an example of a description field that I think would work well for a Get Records element. This example is based on the collection of related Cases to a Contact record.

This element searches for all of the Open Cases in which the Contact that triggered the Flow is the Main Contact. This element will store all of the records found in a Collection to allow for those records to be stored for further use within the Flow.

As you can see, the description is basic enough that it covers what the Flow will do without getting too far into the weeds, but at the same time detailed enough to tell you that the records found will be stored in a Collection (potentially to be used in a Loop). This kind of description will tell an Admin who comes into this Flow to work with it at a later date what the element is doing in a way that is clear, brief, and easy to understand. In my eyes, this is the best kind of way to build out a helpful description field.

#4: Document Things Such as Purpose, Resolutions and Impacts Your Flow May Have

My final tip focuses around document key items around the Flow that don’t fit within what you build at a technical level. Every piece of automation that we build has a reason for existing, they solve business problems and solve a purpose in your org. So all of that needs documenting somewhere. Yes, we need the technical information, but generally that would only be read by Admins, Devs, or other Salesforce professionals who will work on the building and maintenance of Flows within your Salesforce org. This information around purpose, resolutions and impacts will be what will be read by your end users and stakeholders most likely. In one sense, your end users probably don’t need to know all of the technical level of what a Get Element in your Flow does, but they should know and understand why it is there within your Flow. This goes back to the intial point I made about avoiding unneccesary complexity within your documentation of Flows. Now, when it comes to this point there is really two options in my mind. First, you can build one piece of documentation for each Flow, one that covers both the technical and non-technical aspects of documenting a Flow. The other option is you create a technical document, and a non-technical document. Which approach you take is really up to you and your company, both options have pros and cons. The one document model means that you only have to worry about, well, one document for each of your Flows. However, with that model comes a need to try and avoid being too technical in it for the sake of your users who read the documentation. The two document model means you have two documents, both of which need to be kept up-to-date, but it means that you can have one document where you can get as technical as you think is needed, without having to worry about it being too complex to benefit your end users. I personally lean towards the one document model, but there is certainly value in both ends of that spectrum. So absolutely feel free to make the decision you think is right for you.

In terms of what I mean by of the things I list as things to document here, let me provide a brief description of each:

• Purpose: Why is the Flow needed? In brief, what does the Flow do?
• Resolutions: What business problems does this piece of automation solve? Essentially, what value does this Flow bring?
• Impacts: What other items in Salesforce does this impact? Does it affect other Flows, Apex, Approval Processes, etc?

Where possible all of these items should be documented somewhere within your Flow Documentation. Like with all of the things I’ve highlighted in this post, these don’t have to be essays. Just included something that covers these areas will help your users understand why that piece of automation exists in the first place. For example, if you have a Flow that sends an email reminder out to your donors that their recurring donation is about to come to an end and to encourage them to renew, then that information in your documentation is so important, as it explains why the automation was built and gives some good insight into what the Flow does. From a stakeholders perspective, they will often feel like they don’t need to know the details of what automation does, what they often want to know first and foremost is a) does it work? And b) will it help them achieve their goals and objectives. If you can cover that in your documentation in a way that your stakeholders can understand clearly, then you’re on the right track for sure.

Closing Remarks

So those are my top 4 tips to help you create helpful Flow Documentation. What do you think? Do these tips sound helpful to you as a Salesforce Admin (or other Salesforce professional who builds Flows)? Do you think there’s anything that I’ve missed here? Honestly, I’m not a documentation expert myself, I’m simply an Admin/Consultant who has put a lot of time and effort into working out what good Flow Documentation looks like over the last year. Good documentation for Flow is such a gap in the ecosystem right now, so anything that we can offer in the community to help Admins do a better job with it is something that will be a massive help. My hope is that by the end of this blog series that I will have some example documentation templates that you can download, tweak and use in your own Flow documentation efforts. At the time of writing I am almost finished with a template for Record-Triggered Flows, so that should be going live fairly soon. Currently it isn’t ready yet, but my hope is that it will be by the end of March. But that’s it for this week, I’ll be back next week with a post on what you can do within Salesforce to document your Flows.

Also, for anyone who will be in San Francisco for TDX next week, I’ll be there and speaking on the topic of Flow Documentation. So if you’re there, feel free to say hi. I’d love to see you there. It’ll be my first time at TDX, and I’m really looking forward to it.

“Thriving in the Trailblazer Community as an Introvert”
This session will take place at 11:30am PT on Wed 8 March.