Leaving Breadcrumbs
It's kind of a long time since I wrote about documentation. But that doesn't mean I've cooled on its importance. (And my best advice is still just start writing!)
Recently I've been thinking about ways to put documentation right where Future You is going to find it when you need it. I think of this kind of documentation more as "bread crumbs" than as traditional technical or user-focused capital D documentation. Without any plans to be comprehensive, here is my list of places to drop your crumbs. If you've got other ideas, please let me know!
Description Fields
This is the simplest and most obvious place. Salesforce has literally given us a spot nearly everywhere in the platform to leave notes for future builders. Make use of those Description fields!
My personal rubric is that these descriptions should be written for a competent Future You or your successor. That is why, in describing this field, I assumed that any admin looking at this field in the future is going to know what DLRS is. Or if they don't know what it is, they should know that it's important for their understanding and how to access resources to learn about it (like its documentation site). If the admin looking at that description doesn't have that level of competency, they should not be an admin and should not be able to see that description. I am not going to write all descriptions "for a five year old." They are technical documentation to help technical users. (That's why they are different than Help Text.)
We don't need to get silly here. If a field is totally obvious or the description would be duplicative of the help text, I'm fine with leaving it blank. For example, if you have a formula field on Contact called Age, I don't think it needs a description. (It probably doesn't need help text either.)
I'm probably going to catch some flack now from people that want me to suggest that we should now always be filling Description fields because "that's what AI agents are going to look at to understand our orgs." Without going too far down that rabbit hole, I have two responses to that:
Even AI boosters often compare AI to a clueless interns. See my comments, above, about writing descriptions for competent future admins.
The AI agent can take in all the metadata at once (Contact field named Age. Type = Formula. Returns a zero decimal number. Formula is FLOOR(TODAY() - Birthdate) / 365.25) so it should be able to make an inference from that. I know AI does not gain common sense the way humans do, but until it has at least the basics to figure out a field based on characteristics of the field itself, it's not going to be capable enough for my needs. So why should I put extra work into catering to that level of [in]competency?
README Components or Screens
Some readers of a certain age may remember README documents from installing software on their computers. Those probably were read about as frequently as the user manual. But the idea made a lot of sense. Even if you were handed a single floppy disk or downloaded a folder they are a way to include some notes, hints, documentation right where the audience will find it. So why not do the same in Flow?
Sure, every flow has a description and every component does as well. But sometimes, particularly on a complicated flow canvass, you might want even more space. Or you might want to way to call attention because the flow description is not going to be open all the time. So I've made README components on flows.
This flow, for example, is a mess:
That Get Records that's disconnected in the upper left is just a way to call a viewer's attention to a place where I'm going to put notes. (I could have used any other element, but I thought pink draws the eye.)
READMEs are easiest on screen flows because you can use a screen component with a Display Text element to write to your heart's content.
And it's even easier if you aren't using auto-layout because you can just stick that screen near the Start element without actually connecting it in the flow.
In auto-layout this kind of addition will feel a bit more hacky, but I still think it makes sense sometimes. One extra component that does little or nothing, like an assignment at the start of the flow, is not going to significantly impact performance. But the notes might significantly help you out next time you open the flow.
Hidden Sections
Let me start by veering a bit off of Salesforce. On every single Form Assembly form I put a hidden section at the top, like this:
What goes in there can vary widely. Notes about what this form is used for and how. Notes about how to test the form. A reminder of how people will get to the form. If this is a form that either redirects to a second form or is the second (or more) in a sequence of interlinking forms, a note about that is critical. I like to give myself a link that URL-prefills with a test record, similar to what you can see above, or fills some required fields so I can save myself time when testing. Plus I use this section to hold any fields that will be hidden and help power the form itself. Notice that I clearly mark that the section is hidden, includes notes, and holds prefill fields.
I don't do this as often In the Salesforce context because Description fields can often fit the need. And I already talked about READMEs in flows. But if want to leave a note that you'll see when building or modifying a particular screen, you could use this same idea. Just set a Display Text component to conditionally display with some criteria that will be impossible for users to encounter. (Like the screen flow was launched with no value in recordId, the field that lets it know what record it's running on.) Then you can write all you might need.
In a Validation Rule
[This is the one that I really hope is going to blow your mind.]
More than two years ago I wrote about using a before save flow with a custom error component to replace validation rules. At the time I said that I was likely to stick with validation rules because they're simple to update and can be found right in the Object Manager. I still feel this way. But, knowing that I can do the flow method means that if I find myself with a particularly complicated validation situation I have another tool available. And once there is a second place my validations could hide, I need to make sure I remember that. So made a validation rule:
Now every time I go to Opportunities in the object manager for this client I'm reminded that validations are in Flow. No guessing. No "I vaguely remember..." Just easy breadcrumbs for Future Me to find his way.
