4 minute read

Silent killers in your org

Home » Blog » Silent killers in your org
Home » Blog » Silent killers in your org

Scary monsters

Halloween is the one day in the year when LinkedIn is filled with scary stories of ghosts and ghouls. But those managing Salesforce face even scarier things every single day. Many they know about that keep them awake at night – like the super-complex flow that is mission critical, or the opportunity object with 256 record types and 130 pick list fields (yes really!!), or the profiles and permission sets that need to be unravelled before the end-of-life date. ( orgconfessions.com has 1,200 just like these)

But even scarier are the things they can’t see, that are out to get you. The technical debt that has built up over time, and delays every change project. Or the automation and Apex code that could break the org when you make a change.  But the biggest silent killer is something that is impossible to see – missing documentation.

Documentation – the silent killer

A lack of documentation has a massive impact on projects:

  • it extends the time to assess of every change, because the analysis has to start from first principles each time.
  • it creates technical debt, because you a frighted to reuse metadata as you don’t know the impact, so it is safer to create a new, potentially duplicate, metadata item
  • it increases the risk of every change because of there are dependencies that you may not discover during the analysis that breaks the org

Taming the monster

Getting your org documented seems an impossible task as your org – just like everyone else’s – is complex with tons of inter-related metadata. But you can take it a bite at a time, focusing only on the stuff that matters. And you can use preparation for AI as the catalyst to kick off the initiative. 

There is a simple, practical, achievable approach 


1. HOW: How does this part of the Org/business work? 

2. WHAT: What did you change in Salesforce to support it? 

3. 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 –  impact analysis  even before you apply AI. You may want to pick an area to practice and prove the approach that is low risk and low profile. 

For each area do the HOW, WHAT, 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.  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 1,000’s of projects over the last 20 years. 

Here is a process mapping workshop with Ryan Reynolds

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.

WHY – did you do it that way?

And then for each metadata item that you attach, update the Description field.   How you write the description matters now that AI is reading it. You need to assume every word is taken literally.  This means that it needs to be written using very simple, clear english. There are some guidelines from “Plain English” who were established in 1979 to help simplify the way we write.  As they say “Plain language is clear, concise, organized, and appropriate for the intended audience.”   

Here is a blog on how to write descriptions.

The Change Intelligence Platform

Updating your documentation will be significantly easier and quicker if you have a Change Intelligence Platform like Elements.cloud. It builds a lot of automated documentation and gives you a place to hang the documentation. Plus, with ElementsGPT, you can really reap the benefits of great documentation.

Talk to us about setting up your own Proof of Concept.

Ian Gotts, Elements.cloud Founder and CEO, has read all 1,200+ real life confessions orgconfessions.com , and not only has it turned his hair completely white but, more importantly, it’s given him a unique insight into exactly where the ghosts are getting into the machine.

“We know that the top 3 root causes of horror in Salesforce Orgs are Business Analysis, Architecture, and Documentation. Orgs are getting more complex and the scope of Salesforce is becoming broader. We need to find ways to understand quickly what’s working well on the platform and where investment is needed.”

Back to News

Continue reading

Read more news and updates from Elements.