The importance of documenting your Salesforce Org

We all know that documentation is essential. But so often, it gets missed in the rush to release. The issue is that the risks are more significant the next time you come to make changes. Agility needs to be recovered and the value of Salesforce along with it.

Why is it important to document Salesforce?

Salesforce is a strategic application. The power of the application is its flexibility and how quickly it can be configured to support the business’ operational needs. Every customization and integration increases the complexity of the Org. Over time, the risk of making changes increases. The risk is that any change could have unexpected results, or break the Org.

Conducting a detailed impact assessment is the only way to reduce the risk of Org changes. These become longer as Org complexity increases. Documentation on why changes were made, minimizes the risk assessment time. But, documentation when making the changes, takes a fraction of the time, compared to how long it takes to understand why the changes were made days, weeks or months later.

Benefits of good documentation

The benefits of good documentation are:

• Accelerate time to value: The business wants you to make changes quickly, but they don’t want you to break the Org. Without documentation, every change requires time-consuming impact assessment. And there is always a risk you have missed something.
• Reducing risk when making changes: Every change to the Org, introduces the risk of breaking something and end-user downtime. Documentation, can reduce the time to conduct the impact assessment and it can reduce the risk.
• Provide better user support: Troubleshooting issues is faster when there is documentation about why something was configured in a certain way.
• Accelerating onboarding new team members: The faster you can get people up to speed making changes to your Org, safely and confidently, the more effective the team can be.
• Accelerating onboarding consultants: Just like onboarding team members, but they are even more expensive.
• Reduced cost of compliance and security: Every organization has regulatory requirements. At a minimum, there are data security requirements. Some industries such as finance, food, pharma, oil and gas, have requirements that are more stringent and costly to comply with.
• Enabling you to get promoted: If you are the only one who understands how your Org was configured, your management will never want you to leave the role.
• Data quality improves: Documentation on where and why fields are used, means the validation and governance of data can be performed more easily. That leads to better quality data, which AI relies on.
• Exploiting AI: Documentation just got more important. Now, AI can read documentation to make Org suggestions. So suddenly, documentation has become far more critical. But now, documentation needs to be easily read by AI. AI dramatically increases admin user productivity. It accelerates the ROI of your Salesforce investment, by giving you agility back.

So when AI reads your documentation, will it be confused or disappointed?

The 3 Cs in Documentation

Worse than no documentation, is incomplete or out-of-date documentation, that is spread across multiple platforms or systems. It cannot be found. It cannot be trusted. It cannot be used. Process maps and architecture diagrams, in different shared drives and in different apps, requirements in a GoogleSheet, a log of changes in a custom Salesforce object, User Stories as a list of GoogleDocs, then listed in a project management app. You get the point.

As an analogy. You wouldn’t build your CRM with Accounts in a GoogleSheet, Contacts in another GoogleSheet and then each opportunity as a GoogleDoc. All the notes of meetings, in a custom database. And then, leads being captured in a GoogleForm. Customer360 has transformed the effectiveness of sales teams, by getting all the data in one platform and connected.

A “Documentation360” approach, can transform the effectiveness of the teams that drive changes to Salesforce.

The power is the 3 C’s

1. Content: You need all, not just some, of the configuration content to be able to make informed decisions. This means everything related to the core Salesforce platform, customizations and Managed Packages, but also where they are integrated into enterprise on-premise and SaaS apps.
2. Connection: Connecting knowledge content, where ever it is stored, takes a fraction of the time compared with the creation of the content. It can be automatically analyzed and connected. Providing access to the most up-to-date content, saves hours of frustration and wasted time.
3. Context: By analyzing the connected content in context, means we can uncover insights that save costly rework and release roll-backs. This early analysis is core to the Shift Left concept – “the earlier you find issues, the cheaper they are to resolve”. The pace of change, the scale and complexity of Salesforce implementations and the numbers of integrations to other apps, means that this analysis can now only be done automatically.

Documentation overview

Establishing a documentation strategy

Documentation doesn’t happen on its own. It needs a strategy, an approach that makes it achievable and the documentation maintainable. The benefits are clear. But getting the buy-in to spend the time can be a challenge. AI is the perfect excuse.

Why don’t people document, even when they all understand the importance of it?

• No business case or urgency
• It seems like a daunting task
• No time

Suddenly, AI has made the importance of documentation critical. AI can read Salesforce Org documentation and make change recommendations. The time-saving and the improvements in the quality of the recommendations, are staggering. What would take 8 hours, can now be achieved in 5 minutes.

Documentation principles

Whether AI is reading it or not, don’t underestimate the importance of a Salesforce documentation strategy. Only then can you get the benefits from the effort you put in.

Documentation needs to be concise. And it needs to be about why you created the metadata. It is easy to work out what was created, but to be able to understand the implications of making Org changes, means that you need to know why the changes were originally made and who the key stakeholders are.

So here are some principles for documenting metadata changes:

• Generate documentation automatically using the Salesforce APIs
• Follow industry standards: UPN for process, Salesforce Diagrams, DFD, ERD for data models and User Stories.
• Write in an active voice. Use the passive voice only in rare cases.
• Use short sentences as much as possible.
• Use simple everyday words rather than overcomplicating. Here is an A-Z of alternative words. For example, an alternative to ‘as a consequence of’ is ‘because.’
• Omit unneeded words.
• Keep the subject and verb close together.

We created Metadata Description Definition (MDD) as a standard or guide, for documenting metadata items.

Types of documentation

There is more to documentation than metadata descriptions. There are also operational business processes (UPN process maps), architecture diagrams, data flow diagrams, ERD models, change logs, Flow diagrams… and so on. But more powerful than a set of siloed documentation, is when they are all connected. Suddenly, it is all in context and you are building the institutional knowledge or your implementation.

Here are the different types of documentation:

• End User Feedback
• Business Requirements
• Business Process Maps (UPN)
• Architecture Diagrams
• Data Models
• Dataflow Diagrams
• Metadata Descriptions for standard and custom functionality
• Metadata Change logs
• User Stories

Documentation approach

Large complex orgs can be overwhelming with 100,000’s of metadata items and documenting it seems impossible, because it is. So, you need to bite off manageable chunks. But how do you decide where to start? Below is a simple, practical approach that works.

Scope

Firstly, you need to define the scope of the work and this has become easier as organizations are now looking at how AI can dramatically improve areas of your business. Start there. For example, if you are looking at AI for Service, the scope is I2R – Inquiry 2 Resolution. This is centered around the Case object. So let’s apply the 3-step HOW, WHAT, WHY approach, to I2R.

How

How does this part of the Org/business work? Document the Inquiry 2 Resolution business process, using the UPN process mapping standard. It starts with the input, the Inquiry, and ends with the final output – the Resolution. Mao each of the steps in between.

What

What did you change in Salesforce to support it? For each step, link to the key metadata: object, key fields, record types, flows and validation rules. This probably includes the case object and several record types.

Why

Why were changes made and where is the documentation, that describes why and how you changed Salesforce? Document each metadata item you linked in step 2, using the MDD standard. If you have existing documentation such as wireframes, specifications or screenshots, link them. At the same time, you will need an external metadata dictionary as some of the standard metadata, does not have a description field that you can populate and there is no ability to link external documents to description fields. And, document the data model also.

Leveraging a documentation platform

Creating and maintaining a well-documented Org, requires continued investment. It is a huge task, but much of it can be automated using the Salesforce APIs. With the correct tooling, it can be significantly easier. The power is not just in the documentation; you have far more significant insights when it is connected.

A tool suite, or platform, designed to support all the Salesforce documentation types and needs, can make the difference between a well-documented Org, and a documentation initiative being abandoned, because it is just too hard. (Unless you have a very simple Org with minimal configuration and, if that is the case, you are unlikely to get a ROI on Salesforce. You have bought a very expensive spreadsheet.)

It is easy to underestimate what is required to develop a documentation platform that supports the needs. A partial view of documentation, is worse than no documentation. Using the limited free utilities or apps, or building custom objects, is unlikely to support the impact analysis you need. Failing to leverage the APIs, creates a massive manual workload.

The requirements for a documentation platform

There is a good reason why there is a market for documentation platforms like Elements.cloud and why customers can build a clear business case for purchase.

Elements.cloud has been designed to make documenting your Org easy.

• Process maps can be created and version-controlled
• Process map steps can be linked to metadata items in the metadata dictionary
• Architecture diagrams can be created and version-controlled
• Architecture diagram artifacts can be linked to metadata items in the metadata dictionary
• The metadata dictionary is maintained using the Salesforce APIs for each org (Prod and Sandbox)
• Automated documentation is created for each metadata item in the metadata dictionary
• Change logs are created for each metadata item in the metadata dictionary
• Dependencies between metadata items are created
• Notes, descriptions and links to external documents can be made for each metadata item in the metadata dictionary.

There is an industry analyst report, that compares the different apps that can help you maintain your documentation. Elements.cloud is the only “Front Runner”.

The business case for great documentation

The benefits of good Org documentation may be obvious, but to ensure sufficient time is invested in creating it, you need to build a business case.

Here are three aspects that executive management will be able to relate to:

Increasing agility

Arguably, the most significant benefit, is the ability to drive faster changes to Salesforce confidently. That gives organizations the Salesforce agility that they need, to be able to transform quickly. This gives them a competitive advantage – the value of which, is different for every organization.

AI will completely transform how organizations engage customers and support partners and employees in the coming years. The organizations that can be nimble and change quickly, will be clear winners. That requires the ability to change Salesforce quickly, regularly, and flawlessly.

Saving time

A secondary benefit is the time saved for different stakeholders.

The team that maintains Salesforce, faces a dilemma when the Org is not well-documented. We say well-documented, because sparse or poor documentation is often worse than no documentation, as it gives a false sense of security. Either the team moves fast and breaks the Org, which means painful, time-consuming roll-backs and troubleshooting. Or, they move slowly with laborious manual impact analysis for every change. The third option that we see in the most complex Orgs, is that they have put a freeze on all changes.

Business users cannot move at the pace they need as the speed of Salesforce changes holds them back. They either need to wait to implement potential productivity improvements or worse, they have downtime when the org is broken and needs to be rolled back.

AI acceleration

AI can read documentation, create other documentation and make recommendations. For example, it can read a UPN process map and write User Stories. It can read the User Story, make Org change recommendations and suggest and generate code.

With a well-documented Org, AI can be as effective. AI only stands a chance if you, as a human, can understand your Org based on the documentation. But, what AI can deliver when it has a well-documented Org is staggering. It is a game changer and therefore, a massive competitive advantage.

AI has transformed the ROI and importance of documenting your Org.