How to Write Great Documentation

How to Write Great Documentation to Help with Future Problem Solving


We have a pretty cool job as Salesforce Admins. Using our own creativity—and clever solutions we find on Trailhead, in blog posts, through the Trailblazer Community, and alongside the tools Salesforce offers—we can implement solutions that bring success to companies now. And no two days are the same, which is both exciting and fun.

But, like any other cool job out there, there’s another side to the coin. Yes, we’re #AwesomeAdmins, but that means we wear a lot of hats. It’s no wonder it often seems there’s not enough time in the day to even add a new picklist value, let alone remember why we added it or what issues it was solving. As much as I would love to remember every solution I’ve built, and why I chose this tool over another for that solution, the reality is I can’t—and I know you’re in the same boat.

So, how do we help ourselves and our organizations? Who or what is our ally in these times? It’s documentation! (I saw that eye roll!) We know good documentation is important, but just how important is it, really? Let’s break down the benefits together. I promise your future self will thank you.

Why good documentation is important

We know we need to document the changes we make to our Salesforce orgs, but good documentation takes time—a precious commodity no admin is in full supply of. But, there’s a case to be made for the time you will save in the future. Good documentation you write today is a lot more than the time you took to write it. If you’re still not convinced, let’s highlight some of the benefits that come from documenting the why, how, and what it solves of your solutions.

It helps resolve issues more quickly.

Good documentation helps you quickly refresh your busy mind with what flow, formula, add-on, validation rule, or other magic you used to build a solution to untangle where issues are hiding. While Flow Builder is great at showing us where things broke, it’s not the only tool you use and doesn’t always tell the whole story.

It aids the onboarding of new admin staff.

It takes time to ramp up new team members, and the old adage of “have them look at the automation built” is not scalable or even the complete story. Documenting how your solutions that capture the business need were built is like giving your new hire a decoder ring to the org.

It helps update and improve existing solutions to include new elements of a business process.

Business processes often change at a rapid pace. Having your “how and why” solution playbook will increase your efficiency to drill into the existing solution and tweak it for faster re-deployments and improvements.

It can help recycle solutions for solving new business challenges.

I often return to older solutions to grab a complex formula or link to a very helpful blog post that can be tweaked and applied to a different need. While internet bookmarks are great for you, they don’t help your team as you grow or if you change roles.

It identifies existing solutions that can be improved/leaned out with the adoption of new platform features.

Salesforce is constantly improving the platform’s capabilities, which means there are times a solution you built a year ago can be leaned out and optimized with tools available today. Understanding which solutions are using which features makes it a lot easier to prioritize those that need updating.

It helps organize your work to report about the time investment required to build a solution.

Being able to report up and out about what you and your team are working on, as well as the time investment, is critical. It supports your ability to ask for more and give context and data as to why—which can also help you advocate for building/growing a team!

These are some good reasons, but what exactly entails great documentation?

Documenting more than the solution

Documenting the business ask/need is good for providing other context for why you invested your time, and maybe even prioritized the ask over others, but it’s just the start. Great documentation goes further by capturing the following components.

  • What problem(s) is being solved: explaining the user’s story or the business process you’re trying to improve
  • What tools you used to solve it: Flow, validation rules, formulas, AppExchange packages, paid features
  • Why you chose them (over others): cost savings, better user experience, specific features, ease of maintenance, business process alignment
  • What is the purpose of the feature(s) used: the role the feature does and does not play in the solution

Each of these components gives insight and structure to how you and your team apply and use the features available. The first two might seem obvious, but it’s the last two that add real value to them.

Detailing out why you chose the tools you did helps both you and fellow, or future, admins understand your solutioning logic. For example, why did you download that app on the AppExchange? Why are you asking for the business to invest in paid features? What value does it bring to the solution and the business in the future? Be realistic, too. So many features are just plain cool and fun to use, but don’t over-engineer it. Ask yourself, are you trying to put an F1 racecar engine into a golf cart? Maybe you know using a validation rule is leaner than using Flow, but you chose Flow because you wanted the entire process to live in a single place for ease of updating in the future. Context is magic when you return to your solutions. The other hidden dual purpose is you’re actually teaching other admins to think about solutions differently. It’s the same reason we turn to the Trailblazer Community, blog posts, the AppExchange, and peers when we’re trying to design something.

The other element of great documentation is identifying the role of the feature(s) in your solution. Salesforce offers a broad suite of tools. Maybe you’ve covered why you chose to use a flow over a validation rule, but what is the ultimate role of the flow? In your solution, is the flow responsible for modifying existing data, guiding the user through a business process, and creating/deleting records up or downstream? There are no hard and fast rules of what flows should or should not be used for (same for validation rules and formulas), but explaining their role in a solution ensures all the points we called out for the benefits of documentation truly become benefits.

That’s a lot of information, but how does it all come together? How do you determine the role of a tool used, especially when some solutions are complex? Enter the idea of breaking it down and understanding the sections of the problem you’re trying to solve.

Understanding the sections of the problem

When the business challenge or problem statement comes in, our job as #AwesomeAdmins is to dig deeper behind the ask. This investigation often reveals that a full solution has different sections you need to develop or improve for the whole thing to come together. When it comes to documentation, outlining these different sections breaks up the ask and allows you to easily answer the questions above (what problem are you solving, what tools are you using, why you chose said tools, and what role do they play).

If it’s not obvious what sections of the problem you need to develop or improve, then I recommend putting a process diagram together. First, ask yourself these questions.

  • Starting with the end goal in mind, what is the ultimate ask? What does success look like? Usually, this is the tidy, little question the business brought to you.
    • Example: Approved Salesforce quotes are booked as orders in the Enterprise Resource Planning (ERP) via automation.
  • Working backward, what elements are needed for success?
    • Example: ERP orders require a list of products being purchased; all orders must first be approved by Finance before booking; identifying what customer is purchasing the goods and where the goods will be shipped. (Hint: These are sections to your problem!)
  • Knowing the elements needed for success, what are the scenarios you need to consider for each section?
    • Example: What if the product is not active in the ERP? What if the shipping location is brand new? What if it’s a new customer? What if it’s an existing customer? What if Finance rejects the order?
  • What system(s) is the source of truth for what data?
    • Example: The ERP is the source of truth for what products should be available for sale, and Salesforce for the sales price.

The answers to these questions help you organize all the elements needed for success as well as which direction your data/process should flow. With them, you can build the process flows and review them (a lot) with your business.

If you’re looking to get started, I recommend beginning with a pen and paper, or otherwise bringing those questions above to your next business meeting. Once you have the high-level objective captured, everyday tools like PowerPoint and Excel work wonderfully. From there, identifying a central repository to store the information is key. Ensure it’s accessible and searchable for those who need it. For my team, this is Salesforce itself.

Take your documentation to the next level

Building success in an organization means taking your documentation to the next level by elaborating on why you chose the tools you did and what role the tools played. Our businesses rely on us to bring solutions to life, and it’s our responsibility to understand how they fit into the larger picture. Great documentation ensures we don’t forget how all the pieces work together to make the whole. So, go have fun with your documentation and keep rocking it, #AwesomeAdmins! Begin to document all these great nuggets for yourself, your peers, and future admins.

Until next time, happy documenting!


5 tips for getting started with data cloud.

5 Tips for Getting Started with Data Cloud

As an admin, you’ve probably heard of Data Cloud, but maybe you haven’t prioritized it right away because you have other company challenges to address. Well, now’s the time to move Data Cloud to the top and dig in. If you’re thinking, “What is Data Cloud? Can you break it down for me?”, you’re in […]

Product Announcements You Might Have Missed in 2023.

Product Announcements You Might Have Missed in 2023

In the Spring ’23, Summer ’23, and Winter ’24 Salesforce Releases, Salesforce launched hundreds of new features. Make sure you’re up to date on the latest and greatest features for admins by reading about the new features admins were most excited about this year.  Lightning Experience enhancements From new Dynamic Forms enhancements to the Prompt […]

Drive productivity with Dynamic Forms.

3 Ways to Drive Productivity with Dynamic Forms

Salesforce is a great tool for building out custom solutions to meet your organization’s unique needs. You have tremendous flexibility in building out a data model and user interface (UI) that captures all of the complexity of your specific user workflows using our low-code tools. This flexibility can sometimes come at a cost, however. Over […]