What every Org needs — a metadata dictionary

The Salesforce platform is very powerful, and as Spiderman was told: “with great power comes great responsibility”.

With every Salesforce release and with all your customizations, your Org gets more powerful but also more complex.

With everything else you need to do, documenting your changes is probably low on your priority list. But it shouldn’t be. Taking time for documentation will actually make you time in the longer term and greatly reduce the time take to do impact analysis and the risk that changes will break your Org. But how do you convince others — your co-workers and executives? And when you do have the mandate to spend time on documentation and clean up, what is the most effective approach?

ANATOMY OF A METADATA DICTIONARY

Why do I need one? Very simply. Trust & Agility. It is the only way to have confidence that the changes you are making to your Org will not break it when you are making changes at pace. Therefore you need an aggregated view of the metadata and related information.

The best approach is to build and maintain a metadata dictionary where each metadata item in your Salesforce Org(s) (and other systems) has all the related information stored centrally, in context:

• Summary inc API name
• Details e.g. type of metadata and specifics
• Description
• Created and last updated dates
• Related metadata e.g. reports in dashboard
• Where used and dependencies
• Data population (for fields)
• Requirements
• User stories
• Process maps
• Notes
• URL links
• Specifications
• Screenshots
• Photos of whiteboards
• Help topics
• Integration to external systems
• ie. anything that is relevant

This means that the metadata dictionary is not just a listing of all the metadata items in your Org but it is also the central repository for all documentation about the changes that were made. Then it is quicker and easier to conduct the impact analysis to a level where changes can be made with confidence.

PROVIDING IMPACT ANALYSIS INTELLIGENCE

You can use the free office tools, build custom objects in Salesforce, or use paid AppExchange apps to build and maintain the Data Dictionary and manage the documentation. Every approach has its cost. Free is not free. That’s why we are paying to use Salesforce to manage our customer data and not still using lots of disparate free spreadsheets, right?

Here are some considerations as you define your Org documentation approach (spoiler alert – you need tooling designed to work with Salesforce):

• Which Org? Metadata is the Data Dictionary created from Production, Sandboxes and your scratch DX Orgs. How does the documentation “flow” as metadata is migrated through the Sandboxes to Production? The aim is to create documentation when it is fresh in the mind. If you leave it until later, it will not happen as easily.
• How do you keep the Data Dictionary in sync with the Orgs? New metadata items are created daily and modified daily by your team, external consultants or by upgrades to Managed Packages. What happens to the documentation if metadata is deleted?
• How do you merge documentation? You have each working in their own Sandboxes and scratch DX Orgs. How do you merge the documentation so that each team can see what everyone else is doing? This is really important where they are working on the same objects concurrently.
• Which metadata types will the Data Dictionary track? It is just the core platform (sales/service cloud and managed packages) or external systems like Pardot, Marketing Cloud, Commerce Cloud and other apps that are integrated?
• Where are you going to manage and version control the Org documentation? You have different types of documentation — requirements, user stories, process maps, notes, specifications, screenshots — and you need to have version control over them.
• How do you combine Org analysis with Org documentation? You need a complete picture of all metadata to be able to may changes at speed with confidence. Only then do you get full assessment to perform the impact assessment of any changes.
• How do you report on the Org Documentation? How you want to use the Org documentation will determine how you structure and store it.
• How do you control access? You will have different teams who can update, view, collaborate and report on the Data Dictionary and Org documentation. Is it just your Admins? What about developers and external consultants?
• 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?

BUILD STRONG DOCUMENTATION HABITS

The quickest and easiest time to add documentation is “in the moment”. It is fresh in your mind, you remember the rationale- the why.

“I will do it later”. “There is no ‘Later’”.

Nike said it best back in 1988. “Just Do It.”

Take the example of a validation rule. It takes 30 mins to build, validate and test. It could take 2 hours to work that out 3 months later. Adding documentation takes 5 minutes, max. BTW: It could be even faster if you created a process diagram to understand the process that needed the validation rule. Then it is 10 seconds to connect the process diagram to the validation rule. No need to create extra documentation. Or just take photo of the whiteboard / notes and attach them.

At a minimum, fill out the descriptions in Salesforce. Best case, your Release Management processes says you cannot go live unless there is the minimum level of documentation. A quick 280 characters or photo that will be gold dust in 6 months time. A tweet to say “Wow — look what I’ve just created and why.

WHAT APPROACH?

There are several technical approaches that could be used that are free; spreadsheet, Quip document, custom object in Salesforce. However, they fail on every one of the above requirements.

How about: “2 mins to set up and then wait a hour or two for the analysis?”

That is Elements. It provides a metadata dictionary that meets the above requirements and can deal with the most complex multi-org environments.

Run the free 14 day Proof of Concept. . At the end of the trial you could just export the data into an XLS #facepalm