This article is part of the Unpretzeling Your Salesforce Org series by Michelle Hansen. See the other articles in this series here.
Un-Pretzeling An Org: A Guide to Documentation That Won’t Leave You Feeling Salty
Part 1: Why Documentation is Important?
Why is documentation important?
- Have you ever purchased a new appliance or gadget and wanted to know how it works? ..or..
- Have you updated your phone to the latest operating system and needed to figure out where a certain app went (I’m looking at you, “Find Friends,” on iOS 13)?
These are just two examples that highlight why documentation is so important, and it’s no different for Salesforce Admins. Here are a few reasons why I believe it’s of critical importance to document your Salesforce org.
Understanding what has been built before:
Whether your team is expanding, or you’re walking into a mature org, the fastest, and easiest way for someone to get up to speed with your org customizations is to have documentation to review.
- What is the purpose of each custom field or object?
- What automations have been put in place?
- What business processes flow through Salesforce?
- Are any other systems involved?
Just imagine how frustrated you would be if every time you raised a question you had to wait for someone to be available to answer it because that knowledge was never written down.
If you don’t know how something is supposed to work, how do you know that it’s not actually working properly? Further, if you do know it’s not working properly, or at all, how can you figure out where the problem is if you don’t know the steps involved?
Continuous innovation is one of the key benefits of the Salesforce platform, and as Admins, there’s rarely time for us to rest on our laurels after releasing new functionality to our users. Once it’s actually in the hands of your users, they will have suggestions to improve or extend what you have built. If you’re like me, this will usually happen weeks or months after the initial launch, long after I’ve moved on to other projects.
Doubles as training material:
Not only is documentation helpful for your Admin team, but it also pulls double duty as training material, or at least gives you a really good framework for developing that training material. If you’re as busy as I am, anything that saves you time is always welcome!
So Then Why Aren’t Orgs Documented?
Now that you know why documentation is so important, you’re likely wondering how it’s even possible that there are orgs out there today where the documentation doesn’t exist (or is pathetic, at best).
There are quite a few reasons why an org might not have proper documentation.
Here are some of the most common excused I’ve come across:
“I don’t have time.”
Especially if you’re a small team, or you have a large backlog of requests, often the feeling of urgency to develop new functionality leads you to believe that you don’t have time to devote to documenting what you’ve built. “I’ll get to it later when things calm down,” you tell yourself. But as with so many things in life, later rarely comes.
“It’s someone else’s job.”
Passing the buck on tasks we don’t want to do is something we’ve all likely been doing since childhood. For some, documentation is a lot like brushing your teeth or eating vegetables—you know you should do it, and it’s important to stay healthy—but it’s not nearly as fun as watching TV or eating dessert. If you have several roles within your Salesforce team like an analyst, developer, admin, etc. it becomes easier to point a finger at other people and say, “that’s not my job, <insert role here> should have done that.”
“I don’t know where to start.”
Sometimes it’s a lack of knowledge or feeling overwhelmed. If documentation wasn’t stressed as part of your training as an Admin it’s difficult to know what you should document, how, or possibly where. In addition, if you’ve got an org that has been highly customized over a number of years, the task can feel insurmountable. How can you possibly take the time needed to document everything?! You still have a full-time job to do—and this isn’t it. And worse, what do you do first? Paralysis by analysis is definitely a legitimate possibility.
“It’s too expensive.”
Many times, people think the cost of documentation is just too high—either in terms of time (and salary) it will require, or because they assume you need to buy an expensive third-party app to document things properly and that’s just not in the budget. Or they don’t know how to make a business case for documentation to justify the cost, which honestly is probably less than you think.
Talking to Your Boss: Making the Business Case for the Value of Documentation
So now that we’ve discussed why documentation is so important, and we know why many orgs are not documented properly, it’s time to start overcoming those objections and sell the value of documentation to your management team.
Here are a few talking points you can use:
Accelerated Development Schedules:
Having good documentation of what currently exists means you can more quickly start on enhancing that functionality or building new features. Let’s talk about how long it could take for you to dig in and review the existing structure of your org before you could even start on a new project:
- Looking up a Field (3 minutes)
- Accessing a Page Layout (3 minutes)
- Reexamining an Email Template (3 minutes)
- Reviewing a Formula (5 minutes)
- Evaluating a Validation/Workflow Rule (5 minutes)
- Analyzing a Process Builder (10-30 minutes)
- Examining a Flow (15-60+ minutes)
Start doing the math, and you could be spending 4-8 hours just trying to find out everything you need to know before even beginning your new project.
If you don’t know what is actually supposed to happen, how do you know if it isn’t working properly? And if you aren’t sure how it’s designed to work, how can you determine if it’s a training issue with your users or a bug in your code/customizations? Documentation should include what the expected behavior is, such as:
- In what situation this functionality is designed to be used
- Can the user create a record only, or also update a record?
- Should this only be used for specific record types or does it apply universally?
- Are there any prerequisites, required fields, etc. that must be completed?
- How it is designed to start
- Does the user have to push a button?
- Is this automatically triggered by a record change?
- What is the result
- Is a record created or updated with specific values?
- Does an email alert get sent?
- Each step of the process
- Does a Process Builder fire?
- Is a Flow Interview started?
- Is a record created or updated?
Knowing this helps you more quickly diagnose what the problem might be, or at what step in the process the error occurs.
Training is essential for successful adoption within your company, and there are several different types of training you need to prepare with respect to your Salesforce org.
- New User Training: Every person who starts with your company will need to go through this training so they can successfully use Salesforce to complete their daily duties. If you can ‘automate’ this by putting together a training plan that covers the basics that can be used with every new hire, you’re going to save yourself a significant amount of time over the long term. Below are estimates of how long it might take to deliver training on an individual basis. Multiply this by the number of new users you bring on in a year and it starts to add up quickly!
- Basic Salesforce Navigation & Structure (1-2 hours)
- Company Process Training (4-20+ hours)
- New Release Training: Between Salesforce releases and the functionality that you’re developing in your org, there could be a lot of information to pass along to your users throughout the year. If we ballpark the time this could potentially take, you can see how much time can be saved with proper documentation.
- New Functionality (30-60 minutes)
- Updated Processes (10-30 minutes)
- ‘Refresher’ Training: How many times have you held a training event and someone was answering emails or taking other phone calls instead of paying attention to the content? Then, days, weeks, or even months later, they come back to you asking how to accomplish the task that only now has become relevant to their jobs. Well, there’s an easy formula to determine just how much time could be taken up with refresher training:
- 15 minutes * <number of users> * <number of topics> = Days, Weeks, Months
Hopefully this article provided some insights into the need for documentation. More importantly, it gave you the resources needed to help overcome any internal objections and make the business case for the value of documentation when speaking with your management team.
Stay tuned for the next part in this series where we tackle “What Types of Documentation Should I Have in My Org?”