Written by Ian Gotts

AI is reading your descriptions

Descriptions are rarely filled out when metadata is created, even though we know it makes sense. You cannot edit the descriptions for many standard metadata items, and some metadata items do not have description fields.  More on that later. Filling out descriptions is a gift to our future self, and maybe the consultant or Admin who comes after us.

Good documentation has benefits. It speeds up org impact analysis, reduces rollbacks and drives down technical debt. Let’s dig into each of these:

• Org impact analysis: You are about to make a change to a metadata item. If you have a description then it is easier to estimate the impact and the development effort when making a change. 
• Reduces rollbacks: if the team understand how metadata is being used, you are less likely to deploy a change that breaks the org and the need for an emergency rollback
• Drives down technical debt: If you understand how a metadata item is being used, then you can understand whether you can reuse it or change it, rather than creating a duplicate.

All the above use cases are important when it is one of the team or a consultant looking at metadata. Normally they understand context and nuances, they can assess risk, and they can fill in the gaps in knowledge. But now AI is recommending changes to your metadata to deliver user stories. To do that it is looking at your metadata and the descriptions. That is all it has to go on. And AI reads every word and it takes every word literally.

The power of AI as it will consider every possible approach to satisfying a user story and meeting the acceptance criteria. So it looks at every metadata item for every user story. It could recommend changes to metadata that you’d forgotten that you created. And that reduces technical debt and increases agility. 

ElementsGPT can do a decent job just looking at the metadata labels and API Names, but it comes up with far better recommendations when it also has easily understood descriptions. So, suddenly it has become way more important to have well structured and complete descriptions for all metadata items, including standard metadata. 

Here is a demo of ElementsGPT

You will see immediate benefits from getting your documentation up to date even before you implement AI. It is just you now have a great catalyst – the promise (or threat) of AI – that you can use to kick start the project and prioritize it over other work.

This document looks at the emerging standard for metadata documentation – called MDD* – Metadata Description Definition – and how it is applied to Salesforce metadata.

*MDD also stands for major depressive disorder (MDD), is a mental health condition that causes a persistently low or depressed mood and a loss of interest in activities that once brought joy. Which seems very apt.

Principles

Where

The first question is where to document your org. The answer is simple – the Metadata Description field. Trying to maintain a spreadsheet or a text doc, custom object or a Confluence page is unrealistic. And now that AI is looking for information at a metadata level, putting descriptions in 3rd party documents/apps that are not connected to the metadata is absolutely pointless. 

Elements.cloud org metadata dictionary has a description fields for metadata that doesn’t have an editable Salesforce description field. BTW Elements.cloud allows you to build metadata dictionaries for any app  – Data Cloud, Tableau, Mulesoft, Netsuite, ServiceNow etc etc  – and there is a description field for every metadata item.

The benefit of the description field in Elements.cloud is 

• It is available for the metadata that Salesforce has a description field, as Elements pulls from this field on the first sync. You can then enhance it manually.
• Initially, we are extending descriptions for these metadata types (objects, fields, record types, flows, apex classes, profiles, permission sets, permission set groups, validation rules and permission set group)

If you already have a document or app with descriptions, then you can import them into Salesforce and they will be sync’d across to Elements.  Here is an app to do the bulk import into Salesforce.  Mass Update  The good news is, in the future, ElementGPT will be able to help can help validate how good your writing is and can coach you.

Why not What

Most people do not complete the description field. But those who do often describe what the field does. This adds limited value. Looking at the metadata item, and the dependency analysis it is easy to see what it does. And of course, with Elements.cloud this dependency analysis is constantly kept up to date.

Did you know that there is a Salesforce site that lists the description of most (but not all) the standard fields. Sadly most of these are “what” rather than why.  This is to be expected as the authors of this content don’t know how or why you are going to use the fields.  

There are some classic descriptions in this website that add no value at all. For example

Metadata item: Account object, AnnualRevenue

Description: Estimated annual revenue of the account.

Document why the metadata was configured that way, which could be because of business requirements, related to a specific business capability, user needs, or system limitations

Here is a suggestion for a better description:  The amount of revenue for the account is the sum of all closed opportunities (new and renewal). It is updated when the opportunity stage changes. It is reduced if a credit note is issued. It is reported in a dashboard used by execs for their monthly financial review called MonthlyExecDashboard.

Clarity and conciseness

Now that AI is reading the descriptions, 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.”  There are there 10 principles, and here are the 5 that are directly relevant:
 

1. Write in an active voice. Use the passive voice only in rare cases.
2. Use short sentences as much as possible.
3. Use simple everyday words. Don’t use complex words to try and sound clever.  Here is an A-Z of alternative words.   For example, an alternative to as a consequence of  is because https://www.plainenglish.co.uk/files/alternative.pdf
4. Omit unneeded words.
5. Keep the subject and verb close together.

Aim to keep the description to less than 500 characters. Brevity focuses you to be more concise. It also means that you are sending less data to AI, and therefore you are less likely to hit the prompting token limits.

Nuances or euphemisms

This is very similar to the Plain English ideas. Avoid nuances or euphemisms. Often we hide bad news with the passive voice and alternative words. “You will find that the case object status field is no longer activated due to automation requirements.“ A better way of expressing this might be: “We do not track case status using this field. We have a custom field so that we can use it in flow to drive the automation based on the picklist value.”

TLAs only

Every industry is full of TLAs, abbreviations and jargon. We are not suggesting that you can’t use these terms. But they must be understood by AI that has been taught up to Sept 2021 on publicly available content. Therefore, you can use acronyms or abbreviations, provided that they are used throughout Salesforce, IT and your industry. 

Don’t use acronyms that you have made up or that are very specific to your company.  For example RevOps is a well understood term. ReOps is not. Commission is a standard term. Comms is used in telecommunications or PR, and is not the accepted abbreviation of Commission. A simple check is to ask ChatGPT for the meaning of an acronym or abbreviation. 

Assumed knowledge

You need to make sure that there is no assumed knowledge when writing the descriptions. An example of assumed knowledge is that you have a home grown CPQ app and you reused the standard quote object.  This needs to be expressed in each object showing that it is part of the CPQ app and that the standard quote object is being used in a slightly different context. This is clearly a very obvious example. 

But there are smaller examples that cause just as much damage. If you have both a product (SaaS) and services business and both use the opportunity object, the amount field is being used in different ways. The revenue that is product SaaS is invoiced up front but is deferred. The services revenue which is invoiced when it is delivered. And the amount is in US Dollars because you only work in the US. It is worth spelling this out. 

Another example is where you have chosen not to use a standard field, but have created an almost identical custom field. The critical information is why you made this decision, but also documenting in the standard field that it is not used. .  

Here are some guidelines to writing descriptions that will make it easier to create them quickly. Sadly AI can’t really help you because it is your contextual knowledge that we need. It is in the heads of you and your team. 

App or Capability

It is valuable to know that a metadata item supports a capability  – finance, commissions, recruiting – or is part of an app – CPQ, RevOps.  This may be a logical grouping or part of the way you have architected the changes – 2GP.

Managed Packages

ISVs should be documenting their apps, and keeping them up to date. Sadly, very few do. The largest Salesforce ISV is actually Salesforce. They are building huge managed packages to support industries, and smaller ones developed by Salesforce Labs. 

If the ISV managed package is documented, you may then want to overwrite their standard documentation because you are using the metadata in a different way than intended, or in the way that they have described. 

Approach

This is where you roll your eyes. You have an org with 10,000 fields, 1,000 Apex Classes and 500 automations.  Sounds scary, tedious, impossible?  The good news is you don’t need to document your entire org, and you can take it a bite at a time. We have a simple approach that is practical, achievable and helps you make measurable progress. 

“Rather than finding a needle in the haystack, but getting it all out of the barn and checking every strand, let’s pull on the thread attached to the needle.”

As we’ve said before, ElementsGPT can make pretty good recommendations with no descriptions. It simply looks at the labels and API names. But the results are jaw-dropping if there are also good descriptions, which means there is an even stronger reason for completing those descriptions.

WHAT > HOW > WHY

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.  

The Change Intelligence Platform

Updating your descriptions will be significantly easier and quicker if you have a Change Intelligence Platform like Elements.cloud which gives you the analysis and is the single platform to create all the documentation. Plus when ElementsGPT is GA before DF23 you can really reap the benefits of great documentation.

Talk to us about setting up your own Proof of Concept