Posted on November 14, 2022 in Admins 

Complete Guide to Salesforce Documentation

The Salesforce platform is very powerful, and with every release, your org becomes more powerful, but also more complex. As Spiderman was once told: “with great power comes great responsibility”. So, how do you take real responsibility for maintaining your org?

With everything else you need to do, documenting your changes is probably low on your priority list – but it shouldn’t be. Taking just a little time for documentation will actually accelerate future changes because it will greatly reduce the time taken to complete the change impact analysis.

But how do you convince others (coworkers, consultants, and executives) to give you that time? And when you do have the mandate to spend time on documentation and cleanup, what is the most effective approach? This article draws from proven ideas within the ecosystem.

Why Documentation?

How many times have you been about to change a metadata item and wondered, “Why was this done that way?” and more importantly, “What are the implications of making a change?” You may end up wishing that someone (maybe you) had taken the time to add some documentation.

Every change you make comes with the 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.

“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 re-engineer your processes to respond to market changes is the goal of every company – the most innovative and agile business will win. But for most teams, their undocumented org puts a drag on that agility.

There is a strong case for great documentation to ensure that the developers build the right thing: reduced rework, faster implementation, and better user adoption. But there is another benefit.

When future changes are made to these metadata items, the links to the other documentation make it faster and easier to perform the impact assessment. For very little additional effort (i.e. linking documents together), you are building up the institutional knowledge and reducing technical debt. This means every subsequent change is faster and less risky.

1200 Reasons Why – OrgConfessions.com

OrgConfessions.com began life as a few anecdotes 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 confessions, there are over 1,200 – enough data to draw some valuable and startling conclusions.

What you can see from the root cause analysis table below is that the key issues are Business Analysis and Architecture, and the third highest is Documentation. Salesforce has been working hard to provide training and support for business analysis with Trailhead badges and the recent Business Analysis Certification.

The importance of architecture is well understood and Salesforce has launched the Well-Architected program. Interestingly, the business analysis and architecture deliverables are also part of the org documentation.

The 3 Cs of Documentation

Documentation is more than the list of what metadata you added in a new release in Salesforce. We need to add the reason why we added it, as this gives greater insight into how it is used. Instead, it is a combination of different forms of content, connected to each other to provide valuable insights, and delivered in the context of the different audiences using it: business analysts, architects, admins, developers, end users, and regulatory auditors.

The reason for having documentation is so that, when you come back to it in six days/weeks/months, you can understand the impact of changing it.

The first C is Content. Anything created during the implementation lifecycle should not be allowed to reside as a silo of information gathering dust on a hard disk or in the cloud. It is all valuable content.

The power is in the Connections. For example, you can see that metadata items were changed by three user stories over time because of two different business requirements, and they are used in four operational business processes by 17 other metadata items.

When it comes to impact analysis, it is about understanding the Context. This means being able to see the different metadata items that could be impacted by a release, which is a collection of user stories. Then it’s about being able to understand the technical risk (based on the metadata items in Salesforce and other systems) and the business and regulatory risks (based on the operational business processes).

These documents and connections grow over time. Together they are the institutional knowledge of the configuration of the business and supporting systems. They reduce the technical debt because they accelerate impact assessment of future changes. Whilst it may feel that this slows the initial implementation (actually it doesn’t), it also dramatically accelerates future changes.

Below is an ERD showing the interconnections between the different types of documentation content, with the connections and the context, or audiences.

Goals, Feedback, Change Initiatives: These are the drivers of change. They could be very strategic (“we need to implement Einstein”) or tactical (“we need a new picklist item”).

Requirements: These are taking the Goals, Feedback, Change Initiatives and describing them as discrete business requirements that business users can agree to. These are also used in User Acceptance Testing.

Business process maps: The way to validate requirements is to engage business users in workshops to map the business processes being streamlined and supported by the new apps. This is a hierarchical structure of diagrams, with linking and version control. This is the Salesforce UPN (Universal Process Notation) standard that is recommended by Salesforce.

Systems metadata, impact, and dependencies: The metadata dictionaries of the Salesforce orgs (Prod & Sandboxes) kept up to date by nightly sync using the APIs. The automated analysis of the metadata gives impact, dependencies, and field population, plus automated documentation. It can also include future metadata items identified in the design.

ERD/data model and Architect diagrams: These are subsets of the full data model which cover the scope of the solution. An ERD of all the objects is overly complex and does not aid the design. They are also the architectural diagrams showing the system’s interactions. Salesforce has a design standard for these called Salesforce Diagrams.

User stories: The technical definition of the work to be delivered – often called a work item. It is the key handoff document to DevOps, so it is connected to all the other metadata types to provide as much context and information as possible.

“Other” documents: Specifications, wiki, help documentation, meeting notes, whiteboards, brainstorming results, wireframes… All of these can be connected to any of the above documentation types to add more color and context.

Why Don’t You Document?

Here are four potential reasons:

• It seems like a daunting task.
• No time.
• No business case.
• No need!

Let’s deal with each of them:

Scale of Task

One reason we don’t document is because we often believe that documentation is a huge task at odds with our daily demands (and limited time). And perhaps there is the feeling that once we’ve been through the effort of creating it, documentation goes unread – lost in a maze of directories. However, sometimes even a comment, link, or tag can be sufficient.

No Time/Not a Priority

Documentation is a critical part of the configuration, not an optional extra. The cost of poor documentation is very clear – just read a few OrgConfessions!

The IDC Explorer Future of Work survey data showed that 40% of development time is dealing with technical debt. Add to that the time required for firefighting whenever a change breaks an org, and all hell breaks loose! In this sense, it is negligent to build a core business app like Salesforce without documentation.

In his presentation, “Decluttering Your Org”, Christopher Marzilli (Salesforce Product Director, Platform Success) advised us to “devote a percentage of each release to tech debt cleanup (recommend 10-25%)”.

No Business Case

You need a catalyst. Is it maxed-out fields on key objects? Maybe it is the number of changes that are breaking the org? The strongest driver is migrating to Lightning as it forces you to clean up page layouts and evaluate managed packages. Ideally, you’ll redesign operational processes – the basis of all org documentation. Importantly, the Lightning migration will have a budget and executive support.

“Agile” Means No Documentation?

There is a misconception that the term “agile” means something along the lines of: “just build it and see what people think”, and that you don’t need analysis, architecture, or documentation. In fact, agile means delivering smaller chunks of work more frequently.

Salesforce Documentation Approach

The challenge we hear all the time is this: “My org is such a mess, and I have no idea where to start”.

We have this simple 3-step approach that is practical, achievable, and helps with measurable progress – you will probably have some inflight projects you can apply this approach to.

Before we dive into the process, here are some examples we hear 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 too many picklist values and busy page layouts, so we need to look at the Opportunity Object and how to clean up page layouts.
• We’ve reached field limits on the Lead Object so we need to work out which we can delete.
• We need to migrate to Flow – an opportunity to refactor and clean up existing automation. There are multiple process builder workflows that all seem to do the same thing on the Product object.
• We want to start using dynamic page layouts but don’t know which fields are important and which can be removed.
• We want to remove unused managed packages that are costing money.

Step 1: Build a Metadata Dictionary

It all starts with Org Discovery. You need to build a metadata dictionary that will also create a lot of automated documentation – saving you a huge amount of work. Then you can use it to link your manual documentation. Here are a few considerations on metadata dictionaries based on our analysis of over 15 billion metadata items:

• You need a metadata dictionary for each Salesforce org: Production and Sandbox.
• You need a metadata dictionary for other systems outside the core Salesforce Platform: Tableau, MuleSoft, Marketing, Slack, Netsuite, ServiceNow, and custom apps, etc.
• Metadata changes frequently so each metadata dictionary needs to be kept in sync – this could be as often as nightly.
• How do you get different teams, each working in their own sandboxes and scratch DX orgs, to document their work? How do you merge documentation so each team can see what everyone else is doing? This is important when working on the same objects concurrently.
• You should be able to create proposed items, i.e. they are not yet in any org. This is so that you can link documentation. If you leave this documentation until the metadata items have been created, it will be too late.
• Metadata documentation can be created automatically using APIs. Examples include:
  • Descriptions for the Salesforce metadata that has a description field.
  • History of changes.
  • Where that metadata is used (multi-level dependency analysis).
  • How populated fields and picklists (impact analysis) are.
  • How important metadata items (impact analysis) are.
  • Identifying duplications and potential cleanup.
  • When metadata was last used.
• You should be able to add/link manually created documentation to any metadata. Examples include:
  • Stakeholder ownership.
  • Suggested clean-up actions.
  • Links to all the document types (listed earlier in this article).
• You need to be able to report on the information so that you can perform an external analysis.
• You need notification of changes – for example, an installed managed package could be updated and push changes to metadata items you were unaware of.
• The Salesforce Metadata APIs can change with each major release and new metadata types get added. The Salesforce Metadata APIs often throw spurious sync errors which take time to analyze and resolve.
• The sheer size, complexity, and scale of orgs can be significant. A metadata dictionary and the impact analysis could be millions of records.
• Where are you going to manage and version control the org documentation: requirements, user stories, process maps, notes, specifications, screenshots, etc.?
• How do you control access to the teams who can update, view, collaborate, and report on the metadata dictionary and org documentation? Is it just your admins, or will it include architects and developers? How do your external consultants collaborate?
• 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?

You can use the free utilities, build custom objects in Salesforce, or use paid AppExchange apps to build and maintain the metadata dictionary and manage the documentation. But every approach has its costs, which needs to be factored into any decision. “Free” is not free; using a free approach costs the time and effort required in:

• Setting up and maintaining it as APIs change.
• Keeping metadata dictionaries up to date.
• Manually completing the org analysis.
• Fixing a broken org because you didn’t have sufficient impact analysis.
• Business users’ downtime when the org is broken.

The person signing off the Salesforce license cost can build a business case for buying a complete solution for managing all org documentation. They can see the benefits and will budget up to 5% of what they spend on Salesforce. The term for this tooling is a Change Intelligence Platform – more on this later.

So, if you are an admin reading this, do not think that you need to hack together a solution for free (when you know it won’t really support what you need) because there is no budget. Salesforce is becoming a strategic application, and senior management understands that they need to budget for tools: Change Intelligence Platform, Backup, and DevOps, etc.

If you are a consultant reading this, you may be interested in a Change Intelligence Platform vendor. Elements.cloud offers a consultant license at a price that makes it a no-brainer ($500/year) for use on every client engagement.

Step 2: Pick a Project

Do not launch an “Org Documentation” project. This will be too broad and will take too long to complete and showcase the benefits. As a consequence, it will never deliver. Instead, use an inflight or new project to start building out documentation as part of the project lifecycle.

Some documentation is easier than others. You have created a specification, so link it to the impacted metadata items and processes. You have created a new metadata item, so create a note specifying why you did it.

Other documentation may take longer if you are having to introduce more rigorous business analysis before you start building. This is process mapping, it is architect designs, it is the impact assessment of changes, it is writing user stories and grouping them into releases.

There will be huge benefits in user adoption, reduced rework, and fewer rollbacks if you do more upfront analysis. The overall delivery will be quicker – trust me on this. However, there will be huge pressure from the business that sees this analysis as extending the project – they won’t necessarily see the benefits until the project delivers. Plus, there is the natural tendency to want to jump into the build. Please, resist this temptation and fight for sufficient business analysis.

One way to combat this is to point at the scope of the Business Analysis certification and the huge investment in the Well-Architected content being developed by Salesforce. This shows that Salesforce is encouraging and endorsing a more rigorous approach.

Some thoughts on selecting a project:

• Make sure they have sufficient time budgeted to do it in each phase of the project: analysis, build/test, deploy. Give them enough time as they are doing it for the first time and may need to learn new approaches and techniques such as UPN or ERD. They will also need to set up the metadata dictionary.
• Do not leave documentation as a task to complete at the end because:
  • It will be dropped to save time, or the project overrun will eat up the time.
  • It is easier and quicker to document “in the moment”.
• Decide how much you want to change your current implementation approach to include a more rigorous business analysis.
• Make a note of the time it takes to document so you can add the correct budget to future projects.
• Note the time saved in impact analysis because you have a metadata dictionary.
• Track rollbacks (if any) and the overall time from Idea to Adoption.
• Think about how you are going to create the different documentation types and maintain version control and linkages.
• If you have a consulting firm involved in the project, you need to make sure documentation is in their statement of work (SoW).

Step 3: Make Documentation a Key Step in Every Project

Put time aside for a post-project review using WWW (what went well) and EBI (even better if) to help you refine your future project implementation process, budgeting, and approach.

Use the first project as a showcase to roll out the approach to all projects. You need to show the business that the time spent in business analysis and creating documentation gave them a better result, more quickly.

Do not take this as a given. Make sure that you are tracking the numbers from the pilot project so that you can build a strong story.

Finally, the documentation is building up institutional knowledge of your org and systems. Each time you revisit and make changes to an area of metadata that has good documentation you will be able to accelerate the changes with confidence. Make documentation a day-to-day part of every change or action to avoid future issues. After all, some customers will not release changes that are not documented.

Build Strong Documentation Habits

The quickest and easiest time to add documentation is “in the moment” when it is fresh in your mind and you remember the rationale behind it – there is no “later”. In fact, Nike said it best back in 1988: “Just Do It.”

Take the example of a validation rule. It takes 30 minutes to build, validate, and test, but this could take two hours to work out when you’re in the same position three months later. Adding documentation takes a maximum of five minutes. It could be even faster if you create a process diagram to understand the process needed for the validation rule. Then it will take ten seconds to connect the process diagram to the validation – no need to create extra documentation.

As a minimum, fill out the descriptions in Salesforce. Best case? Your Release Management process says you cannot go live unless there is the minimum level of documentation. A quick 280 characters or photo will be gold dust in six months’ time – the equivalent of a tweet to say “wow – look what I’ve just created, here’s why”.

Final Thoughts

What teams have been searching for is a simple, easily implemented, and repeatable approach to cleanup, documentation, and analysis. It needs to work no matter the size or complexity of the org structure, and it must be broader than Salesforce.

There are now a number of paid apps that provide this level of capability, and the market space is called a Change Intelligence Platform.

Independent analyst firm, InVisory, has just produced a research report looking at the different Change Intelligence Platform vendors – both the free and the paid apps. You can download your complimentary copy here:

As the market space is still forming and the vendors are at different levels of maturity, the scope and capabilities are different. Named the market leader, Elements.cloud offers a true multi-cloud solution that provides support for all the documentation across the full implementation lifecycle: feedback, requirements, process maps, architecture, metadata dictionary, dependency and impact analysis, DevOps integration, and in-app help. With a no-brainer pricing model for consultants, they are also able to justify using it!

Elements.cloud has a free Playground where you can sync a DevOrg and practice all the principles we have talked about in this article. Create a free account or reach out to them here.