10 reasons why NOT to use XLS as metadata dictionary

FREE DOES NOT MEAN FREE

It looks so easy and quick. There are free tools out there to dump all the metadata into an XLS. So we’re done, right?

Not so fast.

You wouldn’t use an XLS as a CRM. So, you shouldn’t use an XLS as a meta data dictionary, for many of the same reasons — which I’ll explain.

WHY DO YOU EVEN 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.

ANATOMY OF A METADATA DICTIONARY

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
• Descriptions
• Created and last updated dates
• Where used
• Data population (for fields)
• Requirements
• User stories
• Process maps
• Notes
• URL links
• Specifications
• Screenshots
• Photos of whiteboards
• Help topics
• 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.

METADATA DICTIONARY REQUIREMENTS

Here are some considerations as you set up a metadata dictionary and the org configuration documentation:

• Which Org metadata is the metadata dictionary created from — Production, one of your Sandboxes and your scratch DX Orgs?
• Which metadata types will the metadata 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?
• How do you keep the metadata dictionary in sync with the Orgs as new metadata items are created and what happens to the documentation if metadata is deleted? Metadata may be modified by your team, external consultants or by upgrades to Managed Packages.
• How much “documentation” can be pulled from Salesforce using the MetadataAPI — description, summary, created date, last modified date — and how much can be generated automatically — whereused, risk assessment, field population?
• How do you get the documentation “flow” as metadata is migrated through the Sandboxes to Production, so it is only entered once? The aim is to create documentation when it is fresh in the mind, so as early as possible. If you leave it until later, it will not happen as easily.
• How do you get different teams, each working in their own Sandboxes and scratch DX Orgs to document their work? 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.
• Where are you going to manage and version control the Org documentation: requirements, user stories, process maps, notes, specifications, screenshots etc?
• How do you report on the Org Documentation to speed up the impact assessment? How you want to use the Org documentation will determine how you structure and store it?
• How do you control access to the people who can update, view, collaborate and report on the Metadata Dictionary and Org documentation? Is it just your Admins? What about developers and external consultants?
• Can some of the Org documentation also be reused for end-user help? If so, how do you provide easy access from within the Salesforce record pages to the master versions of documentation?

TECHNICAL OPTIONS

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.

Which is why we developed 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