The Salesforce platform is very powerful. With every new 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. However, it may be difficult to convince people to give you the time to put that documentation in place.
There is now another more important reason for org documentation. And that reason is AI…
AI needs great documentation for two reasons:
1. Data is fuel for AI
AI + Data + CRM. Salesforce is launching AI capabilities that give organizations a huge competitive advantage. But AI requires correct, accurate data. Salesforce has accelerated the GA dates for their GPT offerings.
Most orgs have poor documentation which makes it difficult to be confident in understanding which fields should be used, and how they being are populated
Which field? Tshirt_size__c Size_of_tshirt__c Clothing-shirtsize__c.
Populated by? Page Layout, Flow, Apex, 3rd party integration, MuleSoft
2. Metadata is fuel for AI
AI is reading org documentation so it can make you 100x more effective at maintaining your org. You can have a conversation with your org or the release notes. AI can write documentation. It can create user stories. It can even recommend solutions. And this is just the start!
The better the org documentation, the better the results that AI can deliver. ElementsGPT is already using AI to deliver staggering results.
Why Document?
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 complete no analysis and just hope for the best!
“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. 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.
The reason AI will be difficult to implement is the levels of technical debt. 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%)”.
But now it gets really interesting…
AI Makes You 100x More Effective
AI can read process maps and automatically generate user stories. It creates a user story for every resource attached to an activity box. Those user stories include acceptance criteria and test scripts which are based on the activity box text, the inputs, outputs and resource RASCI (responsible, accountable, supportive, consulted, informed). No one likes writing user stories, and rarely are they 100% complete or accurate. Well, now they are! And, of course, the user stories that are created can also be edited.
AI can then recommend solutions that support the user stories (tailored to your org), while also considering the Salesforce Well Architected framework (architect.salesforce.com). The recommendations include which of your existing metadata to reuse or change, and what metadata needs to be added. These recommendations are based on your org documentation – the metadata naming and descriptions.
AI does a good job just looking at metadata labels and API names, but the results are off the charts if you have descriptions that are filled out. What would take you eight hours is delivered in 2-3 mins. And the results are often better than what you could come up with, because AI has considered every metadata item and also taken into account the Well Architected framework best practices.
AI Needs Standards
To get the best results, documentation needs to follow some standards that AI understands how to interpret. AI is not magic. AI apps are highly tuned prompts that are optimized for the use case. In this situation, it is writing user stories and creating solutions. The documentation standards are as follows:
Business Processes: Salesforce UPN (Universal Process Notation) format. This is an established notation used in organizations of every size over the last 20 years. There are great Trailhead courses. Elements.cloud supports the notation.
Architecture diagrams: Salesforce Diagrams standard. This was introduced by Salesforce in the last 2 years. Lucidchart, Miro and Elements.cloud support the notation.
Metadata documentation: MDD (Metadata Description Definition). Having a standard for this has emerged and been driven by AI. AI reads everything literally so descriptions need to be clear, concise, and unambiguous. Salesforce metadata items have a description field so this is where you should document them. The five principles are Description Field, Why Not What, Clarity & Concise, No Assumptions, and Industry TLAs.
Why Don’t You Document?
Here are three potential reasons:
- No business case
- It seems like a daunting task
- No time
Let’s deal with each of them:
No Business Case or Urgency
You need a catalyst. Well, you’ve got one: AI.
AI forces you to redesign operational processes and understand the data. Importantly, AI will have a budget and executive support. The time is now. The speed that AI is evolving means that you need to sprint to be ready to implement it.
Scale of Task
One reason we don’t document is because we often believe that documentation is a huge task that is 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.
No Time / Not a Priority
Without clear org documentation, you will struggle to deliver an AI project, and this will put your organization at a serious competitive disadvantage. You also won’t be able to take advantage of AI supporting your development.
Even before AI, the current cost of poor documentation is very clear – just read a few OrgConfessions!
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”. People think that they need to document everything. This is wrong, and is actually counter-productive. Document the things that matter.
So, how do you know what matters?
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.
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 add or link your 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 may need a metadata dictionary for other systems outside the core Salesforce Platform: Data Cloud, Tableau, MuleSoft, Marketing, Slack, Netsuite, ServiceNow, and custom apps, etc. But let’s not worry about that at the moment.
- Metadata changes frequently so each metadata dictionary needs to be kept in sync – this could be as often as nightly.
- You should be able to create proposed items, i.e. they are not yet in any org. This is so that you can document them. If you leave this documentation until the metadata items have been created, it will be too late.
- Some metadata documentation can be created automatically using APIs. Examples include:
- Label and API name.
- Metadata specific info e.g. Apex – API and code coverage.
- 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.
- How often metadata was last used (Salesforce event monitoring).
- Identifying duplications and potential cleanup.
- When metadata was last used.
- You should be able to maintain documentation of any metadata. For AI the primary one is the Description field.
- 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 later 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: How, What, and Why
- How: How does this part of the org/business work?
- What: What did you change in Salesforce to support it?
- Why: Why were changes made and where is the documentation that describes why and how you changed Salesforce?
Pick an Area
First pick a capability, app, or project area. Pick the area that has the greatest level of change. Documenting will make the biggest difference for impact analysis even before you apply AI. You may want to pick an area to practice with and prove the approach that is low risk and low profile.
For each area, perform How, What, and Why.
How Does It Work?
How is all about understanding how the business operates and is best described as a simple UPN process diagram. It is how the users use Salesforce to get their job done. It is how that automation or integration works behind the scenes.
Process diagrams are valuable assets and have three audiences. They also have a life beyond the project:
- Admins, Business Analysts and Developers: For app development.
- End Users: Training material to drive up adoption.
- Auditors: For regulated industries process diagrams are the evidence that you are saying what you do and doing what you say.
If you already have process-like documentation (rainstorm flows, flowcharts, process maps, capability maps, SIPOC, BPMN, UML etc.) in other apps and they are still current, then redraw using Elements.cloud in UPN format.
You may think this is a waste of time or rework. However, our 20+ years of experience tell us that:
- It takes a lot less time than you think.
- The content is rarely up to date, so you can streamline it.
- You will be able to simplify the diagrams as you redraw to make them easier to read.
- You get drilldowns, version control, and linking to other assets.
- AI can read them.
Mapping processes can feel daunting, especially when you start talking to IT teams, who often use a complex modeling notation. For business process mapping, we recommend a simple notation that has been proven in thousands of projects over the last 20 years.
Diagrams can be drawn in any format or style but UPN really works, which is why it is the Salesforce standard:
- Draw the diagrams in a simple left-to-right process flow, aiming to have no more than 8-10 process steps per diagram (called activity boxes).
- The activity box is a single, simple building block to show what is done and by who. It is all you need; you don’t need lots of different shapes – trust us!
- You must have lines between boxes with text. These define the handoffs, which is where most processes break down – the more specific the better.
- Any activity box can have lower level “child diagrams”. This makes each diagram simple, with the detail in the lower levels. Think about the three audiences when creating these diagrams: admin/developers, end users, compliance/auditors.
The cool thing about this notation is that there is only one shape to worry about. You can describe any process, no matter how complex, in a way that everyone understands – without any training.
So, the way of thinking about a process diagram is this: what happens in terms of actions (verb and noun) which together produce the desired outcome.
Why do we start it and why do we complete it (input/output)? Who carries these steps out (role/resource) – this could be a human or a system.
How is each step carried out in detail (drill down to the lower level child diagram – blue corner) or link to supporting documentation (paperclip).
What Metadata Do You Use in Salesforce?
Now you work your way through each process diagram step by step and ask the question for each activity step: “What in Salesforce do we use to deliver this step?”
This could be an object, field, page layout, email template, flow, etc. – you can link them to the process step.
Don’t be surprised when you find the same items are linked to a number of different process steps and are used by different departments. This is where documentation becomes a critical resource for impact analysis for any new changes. There is no “right and wrong” here, but decide on an approach and be consistent to help people leverage this. Some people link the highest levels of their process map to the objects involved.
Then, on the detailed lower-level diagrams, process steps may have links to validation rules, specific triggers, or a detailed automated activity that was created in automation.
Ask why you do it that way. Then, for each metadata item that you attach, update the Description field.
Build Strong Documentation Habits
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.
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.
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, and here’s why”.
The Power of a Platform
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.
Having all the documentation in a single platform or app means that you can use the power of the connections between the documentation. AI can then perform its magic and make you 100x more productive.
We like to think about it as the 3 Cs:
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.
Final Thoughts
AI is transforming the power of Salesforce CRM but also how we can change it. AI relies on great documentation. Teams have been searching for 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.