Complete Guide to Salesforce Documentation

Share this article...

The Salesforce platform is very powerful, and as Spiderman was told: “with great power comes great responsibility”.  With every release, your Org gets more powerful but also more complex.

With everything else you need to do, documenting your changes is probably low on your priority list. But it shouldn’t be. Taking time for documentation will actually make you time in the longer term and greatly reduce the time take to do impact analysis and the risk that changes will break your Org. But how do you convince others – your co-workers and executives?  And when you do have the mandate to spend time on documentation and clean up, what is the most effective approach?

This article draws together proven ideas from the ecosystem which can be applied using free tools you already have or using the paid apps on the AppExchange.

Why Document?

Every change you make has a risk that it will break something in your Org.  The impact analysis of every change with an undocumented Org is a huge time suck. Or you simply do no analysis and just hope (by the way, hope is not a strategy).

I love the excitement of deleting a field and waiting for the screams

Said no-one…EVER

Being able to exploit the new Salesforce features and rapidly reengineer your processes to respond to market changes is the goal of every company. The most innovative and agile will win. But for most Admins, their undocumented Org – what developed would call technical debt – kills that agility started as a few anecdotes collected to liven up presentations but it rapidly became clear that there was something more here. Admins wanted to tell their stories to help others avoid the same pitfalls. And everyone wanted to read them, if only to say, “At least my Org is not that bad”.  And whilst we can laugh or wince at these, there is now enough data to draw some valuable and startling conclusions.

We looked at every confession and decided what we thought the root cause(s) could be. We don’t have the backstories since the confessions are anonymous. The vertical access is # of confessions. You see that #3 os documentation.

Documentation – the What and the Why

Documentation is more than the list of what metadata you added in a new release in Salesforce. We need to add why we added it as this gives greater insight into how it is used. In the OrgConfessions, #1 business analysis is business process maps and requirements that explain why you made the changes.

The only reason for documentation is so when you come back to it in 6 days / 6 weeks / 6 months you can understand the impact of changing it. Here is a list of some of the documentation:


The triaged and prioritized list of requirements and user stories. These are in sufficient detail that they are the basis of the testing. Writing great requirements is a key skill.

Business Process Maps

Ideally, this is where all business change starts and how it is described. These are the simple business process diagrams that show the end to end flow of work and how Salesforce can support it. This validates and generates the requirements and user stories.

Data Models / ERD

No org changes should be made without a clear understanding of the data model implications. #2 in the root cause analysis was architecture which is the data model design.

Metadata Descriptions

At a minimum, if the metadata item has a description field – and not all do – then complete it.

Metadata Documentation

Ideally, every important metadata item has more documentation than the 1000 ch in the description field. Salesforce advocates developing a “Data Dictionary” for all metadata items so you can track business purpose, requests but also links to other supporting documentation such as requirements, user stories, business process steps, specifications, screenshots, notes, wireframes and videos.

Commenting Code

Good coding standards should include adding comments in Apex and automation workflow.

User help: This should also be considered documentation, and often the documentation on why the meta item what created can double up as end-user.

Why Now?

Why don’t we document? 3 reasons. No time. Not a priority. No business case. Let’s deal with each of them:

No Time/Not a Priority

Documentation is a critical part of configuration, not an optional extra. The costs of poor documentation are very clear. Just read a few OrgConfessions. The IDC Explorer Future of Work survey data showed that 40% of development time is was dealing with ‘technical debt’. Add to that the time firefighting when you make a change that breaks the Org and all hell breaks loose. It is negligent to build a core business app like Salesforce without documentation. Christopher Marzilli, Salesforce Product Director, Platform Success in his presentation “Decluttering Your Org” presentation said, “Devote a percentage of each release to clean up (recommend 10-25%)”.

No Business Case

You need a catalyst. Is it maxed out fields on key objects? FNO confidence that changes can be made with breaking the Org? The strongest driver is migrating to Lightning as it forces you to clean up page layouts and evaluate manage packages. Ideally you redesign operational processes which is the basis of all Org documentation. Importantly the Lightning migration will have budget and executive support.

We just did a study of 500+ Salesforce customers who made the move to Lightning, and they saw an average 41% increase in productivity

Lightning Experience, Readiness Check Overview

Documentation Approach

The challenge we hear all the time, is “My Org is such a hot mess. I have no idea where to start”. We have this simple 3-step approach that is practical, achievable and helps you make measurable progress.  It is described in detail in the free ebook Chaos to Control

Look at the lifecycle of an object that you are struggling with. You probably have a very clear view of your top 3 hit list.

Here are some examples that we hear about from customers:

  • To migrate to Lightning we need to understand how to simplify page layouts, validation rules and automation, and fix the migration issues for Accounts, Contacts and Opportunities.
  • Users are complaining about slow page loads and busy page layouts so we need to look at the Case Object and how to reduce the fields on the page layouts
  • We’ve reached field limits on the Lead Object so need to work out which we can delete
  • There are multiple process builder workflows that all seem to do the same thing on the Product object.

For the area you are focusing on, follow this simple 3 step process:


How does this part of the org/business work? Document this as a business process diagram.


What did you change in Salesforce to support it? Link each step in the process diagram to the Salesforce metadata items in the Data Dictionary that are required to deliver that process step e.g. objects, fields, email templates, Apex classes, process builder workflows, validation rules.


Why were changes made and where is the documentation that describes why and how you changed Salesforce?  Add or link the documentation to the Salesforce metadata items in the Data Dictionary.

At the heart of this is the WHAT (Org Data Dictionary) which lists all the metadata items.  Attached to each metadata items are the HOW (process maps, data models) and the WHY (documentation and requirements).

Maintaining a Data Dictionary and Managing Documentation

You can use the free office tools, build custom objects in Salesforce, or use paid AppExchange apps to build and maintain the Data Dictionary and manage the documentation. Every approach has its cost. Free is not free. That’s why we are paying to use Salesforce to manage our customer data and not still using lots of disparate free spreadsheets, right?

Here are some considerations as you define your Org documentation approach:

  • Which Org metadata is the Data Dictionary created from – Production, one of your Sandboxes and your scratch DX Orgs? How does the documentation “flow” as metadata is migrated through the Sandboxes to Production? The aim is to create documentation when it is fresh in the mind. If you leave it until later, it will not happen as easily.
  • How do you keep the Data Dictionary in sync with the Orgs as new metadata items are created and what happens to the documentation if metadata is deleted? Metadata may be modified by your team, external consultants or by upgrades to Managed Packages.
  • How to you get different teams, each working in their own Sandboxes and scratch DX Orgs to document their work? How do you merge the documentation so that each team can see what everyone else is doing? This is really important where they are working on the same objects concurrently.
  • Which metadata types will the Data Dictionary track? It is just the core platform (sales/service cloud and managed packages) or external systems like Pardot, Marketing Cloud, Commerce Cloud and other apps that are integrated?
  • Where are you going to manage and version control the Org documentation: requirements, user stories, process maps, notes, specifications, screenshots etc?
  • How do you combine Org analysis (field usage and field data population), with Org documentation so you get full picture to perform the impact assessment of any changes?
  • How do you report on the Org Documentation to speed up the impact assessment? How you want to use the Org documentation will determine how you structure and store it.
  • How do you control access to the people who can update, view, collaborate and report on the Data Dictionary and Org documentation? Is it just your Admins? What about developers and external consultants?
  • Can some of the Org documentation also be used as end-user help? If so, how do you provide easy access from within the Salesforce record pages to the master versions of documentation?

Build Strong Documentation Habits

The quickest and easiest time to add documentation is “in the moment”. It is fresh in your mind, you remember the rationale- the why.

“I will do it later” 

“There is no ‘Later’” 

Nike said it best back in 1988. “Just Do It.”

Take the example of a validation rule. It takes 30 mins to build, validate and test. It could take 2 hours to work that out 3 months later. Adding documentation takes 5 minutes, max. BTW It could be even faster if you created a process diagram to understand the process that needed the validation. Then it is 10 seconds to connect the process diagram to the validation. No need to create extra documentation.

At a minimum, fill out the descriptions in Salesforce. Best case, your Release Management processes says you cannot go live unless there is the minimum level of documentation. A quick 280 characters or photo that will be gold dust in 6 months time. A tweet to say  “Wow – look what I’ve just created and why.

Quick wins

There are some quick wins that can give you a huge return in a few hours, and can build the business case for a more robust approach and tools. We wrote a book called Rapid Results which sets it out in more detail.  The book suggests 3 areas:

  • Remove fields from page layouts: Simplify page layouts which will speed up page load times, engage end-users and reduce data entry errors.
  • Collect feedback and add help on fields: Look for fields that need more help – picklists, mandatory, validation rules, kick-off automation – in page layouts. Collect feedback with a quick cycle time to respond to users with updated help to keep them engaged.
  • Remove unused Managed Packages: They bloat your Org and waste money on unused licenses. Whilst this doesn’t directly improve user adoption it is a great source of cost savings. Catalyst

What Admins and Consultants have been searching for is a simple, easily implemented and repeatable approach for clean up and documentation. It also needs to work no matter the size or complexity of Org structure. And it must be broader than Salesforce.

We’ve spent the last 4 years building Elements Catalyst to provide a robust tool that support all the Org documentation issues which is why we win DemoJam after DemoJam. We are finding that customers are able to build the justification for a more robust approach than spreadsheets. The free trial set up take 4 clicks and 2 mins.  The nightly analysis on your Org will be insightful (and potentially scary).

8 thoughts on “Complete Guide to Salesforce Documentation

  1. Great article!! Love it. It is difficult to convince teams to stick to the basics. Keep it clean, controlled. I have personally spent 70% of development time simply analyzing org because documentation is absent. It’s frustrating and so difficult to explain and justify. We are so capable of messing up a good ecosystem at a fast pace!

  2. At a minimum, a screenshot can be taken of the change set details, and added to the ticket. This way when supporting the functionality, you at least have the components of what was built. Crawl. Walk. Run.

  3. Great overview of a solid process. Documentation is one of those things thats so hard to keep up and it takes a lot of “will power” to keep it going. I’ve never seen Elements Catalyst before but it looks great.

Add Comment