Help!!! Documenting My Flows is Really REALLY Hard!!!
Documenting Flows Can Be Difficult … Let’s Help with Four Top Tips
Honestly, one of the biggest gaps in the declarative automation realm is good tools to help Automagicians (yes, that’s a thing now) document their pieces of declarative automation in a productive and helpful manner.
In this blog I’m going to give some brief tips on how you can document your Flows well, and with full transparency here, I am not an expert in this area. Like you probably do, I really struggle with my Flow documentation. However, I still feel like I can provide some tips to help you and I along the way. Tips that will help us be more strategic in our documentation efforts.
So, with that being said, let’s begin. First allow me to unpack why I think documenting our declarative automation is important with a little context.
It All Started When I Became a Consultant
So allow me to be honest right off the bat, a lot of my thinking on how I do my day-to-day work has begun to evolve ever since I became a Salesforce Consultant last year at Cloud Galacticos. So much of this is thanks to them.
Simply put, the shift in my thinking started to come when I began to understand that the work I did had to be done in such a way, that whoever was given the keys to my work after I moved on from a project needed to be able to understand my work from the beginning. Now, am I saying that I’m a perfect consultant or that I apply this thinking as well as I could? Well, probably not just yet, but I do think that I’m getting better at it as I go.
See, the reality is that there is a vast difference between how a consultant works, and how a Solo Admin works (which is what I was previously). And the main difference so far for me, is this knowledge of whatever I build has to be understood by the person/people who come after me to maintain what I’ve built for them. This has begun (in a positive way I think) to affect how I design my Flows. Rather, than simply designing Flows to perform well and make sense to me as the Admin, I have begun to think about the design principles that underly our Flow building, and how that affects the people who will maintain the Flows we build after we move on and leave them to it. I don’t build Flows anymore for an org that I am staying with for the longterm, instead I’m building Flows for clients I may no longer be supporting in the near future. This has really begun to shift my mindset.
So with that context out the way, here are my documentation tips.
4 Tips for Improving Flow Documentation
Here are my 4 tips for improving Flow Documentation as an Admin:
#1: Use Description Fields as Much as Possible
First and foremost, use the description fields in Flow as much as possible. This is something that is a good practice across the board, but in Flow this is something that I think is now a necessity. Doing this will allow you as the Admin to understand what the purpose was for each element in your Flow.
Here are some guiding principles to using descriptions in Flow:
- KISS … keep it simple “stupid” … I’m not saying you’re stupid btw.
- Explain what that element, component, action is for.
- Remember that this has to make sense to someone who isn’t you.
#2: Create a Change Log That Highlights Key Changes to Your Flow
Next up, I want to mention the idea of keeping a change log of your Flow. As an Admin you may have heard or implemented change logs in your work. If you haven’t, don’t worry, I’ve got you covered. Let’s explain.
A change log simply is a document where you note key changes to the thing your change log is in reference to. In this case, we’re talking about a Flow. In a change log, you will usually include a contextual overview of key changes that were made to something, and the reasons for those changes. The reason for this is once again to help others understand what changes have been made, why they’ve been made and what they should do in the instance of a need for future changes. This is a key part of documentation.
Regarding Flow, here’s what I would recommend including in a change log:
- The date (and maybe time) of your change (this is an absolute MUST).
- A brief description of what has changed in your Flow.
- The version number of your Flow (this will help monitor the versions).
- Additional and relevant information that can’t be added to descriptions.
#3: Create a Naming Convention for Your API Names
As much as I love Flow, and believe me, I absolutely LOVE Flow. One of the things I find myself not really liking anymore as I’ve gotten more advanced in Flow, and after having worked with a really great Architect on a project recently at Cloud Galacticos, is the default naming conventions for API names in Flow. Spoiler alert, this might come across as a little bit snobby.
So here’s my unapologetic and unabashed opinion. I do not like the default API naming convention for Flows in Salesforce anymore. I prefer to use a naming convention for EVERYTHING in my Flows. Now, again to be fully transparent here, my naming conventions is something that is evolving. And that’s OK. As we become better at Flow building, our architectural and design-level thinking can and absolutely should evolve as we get better and improve as Flow builders. So by the time you’ve read this post, my naming conventions may have changed slightly again … and that is not hyperbole.
The guiding principle of a naming convention in Flow should be two-fold, it should explain what the item is, and it should make sense. That’s it! It is really just that simple. Granted, we can begin to get a little more advanced with it and try to bring our naming conventions more in-line with what we see in coding languages such as Apex (this is what I’m working towards). However, at the very least, if you follow these two guiding principles, you’ll be set up for long-term success as an advanced expert Flow Builder.
I won’t dive into too much detail on this point, as that will come in another post. However, before we move on, allow me to provide some examples of what I currently consider to be good naming conventions via comparisons.
Here are 2 examples of good naming conventions:
- Assign element = setDescriptiveName
The descriptive name should be something that explains what is being set in the Assign element. For example, setNewOppCollectionValues. This example would indicate that you are working in a loop and are adding values to either a singular record in a collection of opportunities, or updating the collection. - Create element = createNewObjectRecord
The portion of Object in NewObjectRecord should be replaced with the name of the object that you are creating records for. For example, if you’re using your create element to create new Opportunity records, then the naming convention would be createNewOppRecord. I am currently trying to abbreviate the name of the object in question. So in the example I am giving here, the Opportunity object would be shortened to Opp to denote that the records being created in this Flow are new Opportunity records.
FYI, I’m hoping to be able to deliver sessions on naming conventions in the future. I’m currently working on a repository for Flow naming conventions that could be accessed by any Trailblazer who wants to start using it.
#4: Always Be Building Up and Improving Your Documentation Style
Finally, the point I want to wrap up this post with is the one that says that the best documentation styles (in my opinion anyway) are ones that change overtime. See, the truth is Flow is always evolving and changing. Less than a year ago at the time of writing we didn’t have formulas available in our entry criteria for Record-Triggered Flows. Now, not only do we have that, the improvements that it brought to formula syntax checking in Flow are now being applied more generally within Flow builder itself. And that’s quite a small example by comparison. But this points to a guiding principle that Flow is always evolving. And we should be able to evolve with it.
As expert Flow Builders, we should be improving our documentation style to match what is the current state of Flow building. For example, if my idea of being able to export the Flow canvas similar to what we can do with reports and dashboards ever happens. Then we should begin to include renders of our Flow canvases in our documentation templates and efforts.
Here are some guiding questions that I think are highly relevant here:
- Do changes in the most recent release/s affect my documentation style?
- Has my naming conventions changed in a way that affects things?
- Is there general improvements I can make to make it easier for others?
Closing Remarks
So that’s my thoughts on how you can level up your game with a variety of techniques for Flow documentation. I’d love to hear what you think in the responses below or on social media. I’m delivering a session on Slack and Flow Orchestrator on Thursday at Dreamforce, and this blog post will be included in the resources section there. So please do check this post out, and share your thoughts with me. I’m always looking to improve my Flow game, so if you have any good documentation ideas for Flow, let me hear it.
