At TrailheaDX they ran the Declutter Your Org session 4 times, showing the importance of cleaning up your Org. Attendees got to post questions in the chat and there were some questions that came up time and time again. The presentation ( link to the recording …when available ) highlighted the importance of a data dictionary but they gave no advice on how to create, maintain or use it. Not surprisingly this prompted a ton of questions in the chat:
Will Salesforce be launching any tools for technical debt analysis/cleanup beyond optimizer? There are free tools like FieldTrip, PermComparator, but they are rather simple.
Is there a sample Data Dictionary available, or template?
Is data dictionary an out-of-the-box solution provided by Salesforce?
Any automated ways to create a data dictionary?
Are there any tools to start the creation of a Data Dictionary? Feels like this could be pretty intensive to try and create this manually.
Best practice for creating and maintaining documentation, especially as you move forward in removing technical debt?
A while ago I wrote an article about maintaining a data dictionary, which is below. Spoiler alert: it is more than dumping the fields into an XLS.
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
- Created and last updated dates
- Related metadata e.g. reports in dashboard
- Where used and dependencies
- Data population (for fields)
- User stories
- Process maps
- URL links
- 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.
Maintaining a Data Dictionary and Managing Documentation
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:
- 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.
I want one — now
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: “1 min 58 secs to set up and then wait a hour or two for the analysis?”
That is Elements Catalyst. 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 trial. At the end of the trial you could just export the data into an XLS #facepalm