This article is part of the Unpretzeling Your Salesforce Org series by Michelle Hansen. See the other articles in this series here.
What Types of Documentation Should I Have?
While this is not a comprehensive list, there are several types of documentation that I’ve found to be essential if you want to keep your org clean and organized:
- documentation for your users, and
- process documentation.
Each of these play their own unique part in your documentation strategy, but all together, they can help create another important piece of documentation—an Admin’s Handbook.
This is a guide with all of the critical information needed to keep your org up and running, and most importantly, should also include what not to touch. The Admin Handbook is especially helpful when you will be out of the office, maybe on vacation or at a conference.
Considerations About Documentation
Before we dive into the details, let’s talk about a few considerations you should keep in mind when creating your documentation.
Who are your audiences?
You’ll never have just one. You’ll need to keep the rest of your admin (or dev) team, users, and management informed about changes to the org, but the level of detail each group needs will vary widely.
This may require you to create different versions of documentation tailored to the needs of each group, or perhaps create a single document with varying degrees of detail so your management can stay up to date on the highlights while users can get the details they need.
When documenting processes, you need to look at your inputs, main actors and outputs. So, who are all of these people (or things, for that matter)?
Let’s take a sample process: Approving and paying expense reports.
Your input would be the employee who submits the expense report to their supervisor.
The main actor, then, is the employee’s supervisor who reviews and approves the expense report for payment by the finance team.
In this situation, the outputs are both the approved expense report and the finance team who will process the report.
What are their knowledge levels?
- Is your documentation sufficient for someone with no experience to complete the process from start to finish without assistance? or
- Do you expect them to have a baseline level of knowledge about your industry, Salesforce, and your company’s org?
The answers to these questions will inform the way you approach your documentation, especially the level of detail or the use of acronyms or ‘jargon’.
How will it be consumed?
You’ll also want to keep in mind where your users will access this documentation:
- Are they always going to be sitting in front of their computer? or
- Will they need to access this from a mobile device?
If you’ve ever tried to read a PDF on your cell phone you know how frustrating it can be when something isn’t form factor responsive. You might also have some employees who are still ‘old school’ and will print out any instructions you provide, which means they could quickly become outdated.
What format should you use?
Most of the time when people think documentation, writing things down is the first image that comes to mind. But as outlined above, there are a number of considerations that may lead you to choose a different format than the written word, like video. Depending on the topic, you may want to do quick overviews of functionality that is being released, or step-by-step walkthroughs where you can show users how to complete a new process.
Now that we’ve outlined some considerations you should keep in mind, let’s dive into the types of documentation you should have.
Types of Documentation
Org customizations encompass the custom objects, fields, formulas, validation rules, etc. that you’ve built. Documentation of these customizations can, and should, happen in Salesforce. The Description field, along with the Data Owner, Field Usage, Data Sensitivity Level and Compliance Categorization fields, are exactly where you should store this information, including:
- Who requested the field?
- What purpose/business unit/process does it serve?
- Who or what does it support?
- Where is this field used? Reports, Dashboards, Automations, etc.
- How is it populated? Will users fill in this field or does an automation populate it at a particular point?
Comments are not just for developers and Apex code! Formula fields and Validation Rules can be tricky to read—sometimes it feels like the syntax is a different language! One suggestion I often give Admins who are struggling is to write out what you want the formula to do ‘in English’ first, and then ‘translate’ it to formula syntax. You can then comment out the English version within the formula field itself to help others read it more easily in the future. The syntax for comments is to precede the text in a forward slash and an asterisk, then follow it with asterisk and forward slash, like this:
Here’s an example of how this might look in a Validation Rule where we want to ensure that the Billing State is filled in for all Business Accounts:
/*Check that the Account Type equals Business Account*/
/*Check if the Billing State is blank*/
Don’t forget, you also have the option to document this outside of Salesforce, and there are a couple of Excel-based templates you can use for this, depending on how you decide to approach it. The first is the Master Configuration Workbook, which I found in this Admin Hero blog post. This template allows you to document your org object by object, detailing the type and purpose of each field, which ones are required, and even which are in use by each page layout.
You might instead (or also) decide to document your org by release. This is something I’ve found especially helpful in building my Change Sets when I’m ready to move my new customizations from sandbox into production. By documenting every new thing I’ve built as I go along, it serves as a checklist when it’s time to deploy. Not only does it include detailed information about new fields, but it also has a place to add the things you might forget about like permission sets, processes, validation rules, etc. And as a bonus tip, don’t forget to add impacted profiles to your change set as well!
Documentation for Users
There are two types of documentation that are specifically designed with your users in mind. The first type is Release Notes. Many of us spend countless hours developing or improving functionality in Salesforce to help our users do their jobs more quickly and easily. But while the mantra “If you build it they will come” worked great in Field of Dreams, it probably won’t have quite the same effect for your busy users. Communication is vital to let your team know about changes to Salesforce that will impact their jobs, especially when making changes to already established processes or procedures. This is something Salesforce does remarkably well with their thrice-yearly releases, and if it’s good for Salesforce, it’s good practice for us as Admins as well.
While I definitely encourage you to have a paper/PDF version, the format of your release notes is up to you!
Much like Salesforce there are a number of other ways to get this information out there, including training events or videos (Release Readiness Live, anyone?). It’s important that you talk to your users about what formats/delivery methods work best for them so you can ensure all that hard work you’ve put into your org is adopted.
Below is an example of Release Notes that I put together. There are several items that I like to include in mine:
- Release Date
- This is the date we released this functionality into production.
- Salesforce Release Logo
- I include this both because I like how it balances the page layout and creates some visual interest as well as to help quickly identify which Salesforce release these changes were released on (plus I just love the characters!).
- Salesforce Release Version
- I include the version that was live when my changes were deployed to help me troubleshoot if something breaks with a future release, and because the logo is often too ambiguous to definitively tie to a release.
- Release Highlights
- These are one sentence overviews for each item released. If someone doesn’t have time to read the full notes, this should give them enough information to understand what new functionality is available, and from there they can decide what they need to learn more about.
- Object Icon
- I like the visual design element and also use this to help cement the users’ association between the functionality released and the icons used in Salesforce.
- Functionality Details
- This is where I go into detail on what was released. I include information on why this is needed, what issue or need it addresses, and list out what fields were added or what the process steps are.
- Link to How-To Documentation
- Especially if this is a critical new process, significant changes to an existing process, or has more than 3 or 4 simple steps, I make a point to develop How-To documentation and link to it from my Release Notes.
- We’ll go into more detail on How-To docs in the next section.
- Company Footer including Internal Use Only/Proprietary & Confidential/Etc.
- Your Salesforce org and customizations are more than likely considered intellectual properly and you should take steps to safeguard it. Check with your Compliance or Legal team to determine what you should include for this purpose. The footer also provides some additional visual interest and breaks up the text on the page.
The second type of documentation for Users is the How-To document. This is meant to be a step-by-step instruction manual for the users to perform a specific task or process. I generally try to approach these with the expectation that someone with little to no experience with Salesforce at all should be able to follow the instructions provided and successfully accomplish whatever is covered in the How-To document. With that in mind, I make sure to include plenty of screenshots and explain each step in sufficient detail, often accompanied by a numbered list of steps. Below is an example of a How-To document we created on how to submit a request for assistance to our Salesforce Admin team. As with Release Notes, there are a few pieces I make sure to include in my How-To docs:
- Overview section
- It’s human nature for people to ask, “what’s in it for me?” As we all lead increasingly busy lives, it becomes necessary for us to decide what we will give our attention to, and things that make our lives easier, or are personally important to us will win, which is why I include information about why this functionality has been developed and what benefits it will provide to the users.
- Section navigation
- Especially if there is branching logic in the process, I break the document up into sections using section header functionality. This not only provides some visual interest on the page, but also helps users quickly navigate to the section(s) relevant to them.
The third and final type of documentation we’ll cover is process diagrams. You’ve all heard the adage that a picture is worth a thousand words, and the focus of analytics is to use charts and graphs to more easily display data so users can make better informed decisions. This same principle comes into play with process diagrams. These are visual representations of a process, which are much easier to follow than pages and pages of text. There are two types of process diagrams that I want to address—Business Processes and Automated Processes.
Business Processes encompass how your team conducts the business of the organization. This more than likely will include systems other than Salesforce depending on how your company is set up, but it is necessary to have a good understanding of these processes and the role Salesforce plays within them. Plus, helping create this documentation can increase your value to the organization beyond your skills as a Salesforce Administrator.
Automated Processes within Salesforce is a category I’ve never really seen addressed before, and definitely caused me some heartache as my org became increasingly complex. The power of the Salesforce platform means you can perform many actions with a single record update, or click of a button, and keeping track of all of the moving pieces can be a challenge. For me, there was nothing worse than forgetting to account for a piece of an automated process when building new functionality and becoming increasingly frustrated when I couldn’t figure out why it wasn’t working properly.
A Few Final Notes
It’s vitally important when you begin documenting your processes to accurately depict the current state, no matter how messy, disorganized, manual, or seemingly embarrassing it is to capture it on paper. Once you’ve gotten the current process documented, it’s much easier to start identifying pain points, bottlenecks, and other areas for improvement, prompting your team to unleash their creativity and begin sketching out the ideal future state.
Much like GPS directions, it’s really hard to figure out how to get where you’re going if you don’t know where you’re at. So be brutally honest in your assessment and documentation of how things are done today—it really is worth the effort in the end.
Depending on the tool you use to document your processes, it can also offer you the ability to create multiple layers to your processes, offering the ability to display different degrees of detail for your various audiences. Consider the amount of information about a process that a Salesforce Admin or Developer may need—what fields or automations are involved, whether there are other systems in scope, etc.
Think about what your users or management team will ask for—what tasks they need to perform to accomplish the end result—with no regard for the technical details going on behind the scenes.
This article is not meant to be a comprehensive list of documentation types, but at the very least it will get you started on the journey to good documentation, and gave you some guidance and templates that you can use along the way.
Stay tuned for the next part in this series where we cover “How Do I Document Processes?