The Importance of Dynamic Documentation in Salesforce

Today on the Salesforce Admins Podcast, we talk to Jonathan Fox, Head of Salesforce Architecture at IntellectAI. Join us as we chat about why we should rethink how we label, structure, and maintain Salesforce metadata.

You should subscribe for the full episode, but here are a few takeaways from our conversation with Jonathan Fox.

How do you know if your metadata needs to be cleaned up?

When we were trying to implement Agentforce on the Admin Evangelist org, we came to a sobering realization. Despite all the content we create on how to do things the right way, it turns out that we all approach metadata a little differently. That’s why I was so excited to sit down with Jonathan to talk about how to clean up your metadata for AI.

Training an agent is like showing your org to someone who knows nothing about your business. Suddenly, it’s really important what the labels mean and that they’re consistent.

Start small with metadata

The thing about technical debt is that it’s not a problem until it becomes a problem. Your metadata is probably fine for most of your users, who have a working knowledge of your business processes. It’s only when you try to implement Agentforce that you realize you have a problem.

Jonathan recommends that you start small when you’re trying to clean your metadata. Roll out Agentforce for a small use case and only clean up the metadata associated with that specific task. If you need to generate buy-in, try running Agentforce as-is and then show your stakeholders just how much difference a little bit of cleanup can make.

Metadata is the foundation

“Your metadata is the foundation of your Salesforce org,” Jonathan says, “you don’t want to get it wrong, you don’t want to make it worse. So it needs to be treated with that respect and that kind of importance when you’re changing it.”

Documentation is the key to making sure that you’re keeping things usable for human and AI employees alike. You need to make sure that you fully understand the impacts of any changes you’re implementing, or you risk breaking all sorts of automations in your org.

Jonathan had so many more great insights about how to start cleaning up your metadata for AI agents, so be sure to listen to the full episode. And don’t forget to subscribe to the Salesforce Admins Podcast to catch us every Thursday.

Podcast swag

• Salesforce Admins on the Trailhead Store

Learn more

• Salesforce Admins Podcast Episode: How Are 2025 Admin Predictions Holding Up So Far?

Admin Trailblazers Group

• Admin Trailblazers Community Group

Social

• Jonathan on LinkedIn
• Salesforce Admins on LinkedIn
• Salesforce Admins on X
• Mike on Bluesky social
• Mike on Threads
• Mike on X

Full show transcript

Mike:
Welcome to the Salesforce Admin’s podcast, and hey, how did we do last week? Did you listen to that episode to see how our 2025 admin predictions were holding up? If not, add that to your play next list, because that was a fun look back. I like listening to things from the past, but let’s go ahead to the future. So in this episode this week, we’re joined by Jonathan Fox, who takes us behind the scenes on something every admin deals with, and maybe you don’t think you do, but it’s metadata. And in fact, in next week’s episode, we’re going to talk about cleaning data, so buckle up folks. It’s summer cleaning time.

But the fun thing is we start off with a conversation around a barbecue that sparked Jonathan’s career and got it into amazing directions. How many people talk Salesforce over barbecue? And Jonathan also helps us rethink how we label, structure and maintain Salesforce metadata. So whether you’re prepping for Agentforce or just going through an org and wondering what some of those data labels mean, I promise you, this episode is for you, and if you love what you hear, be sure to give us a favorite or a review on iTunes. But with that, let’s get Jonathan on the episode.

So Jonathan, welcome to the podcast.

Jonathan Fox:
Thanks for having me. I’m excited to be on.

Mike:
Well, I’m excited to tackle this because we’ve bounced around and I’ve done a few episodes on cleaning data and cleaning metadata and back and forth and back and forth, and I think it hit our team like a truck when we were working on implementing Agentforce in our org, and Josh, who was working on it, came to the realization that despite having three or four evangelists on the team, we’d all named fields differently and we’d all done things a little different. And he’s like, “We really have to talk to people about metadata.” And we’ll get into that and we’ll have a follow-up episode on data data, but Jonathan, let’s hear about you. How did you get started with Salesforce and what do you do?

Jonathan Fox:
My journey into Salesforce was, well, most people say this, a little bit unorthodox. My background is the military in the British Army, and I stumbled across Salesforce, family barbecue. My brother-in-law brought me into the Salesforce world and taught me how to be a developer basically, and I worked my way up through-

Mike:
At the barbecue?

Jonathan Fox:
At the barbecue, yeah. That was the riveting conversation we were having over beers and burgers, was Apex in fact. Not quite metadata, but at least a bit of Apex was the topic of conversation. He taught me how to get started in tech and how to be a developer, and the rest is history as they say.

Mike:
I feel like that was the one line that he’s telling his significant other. “No, this line’s going to pay off. I’m going to find somebody at a party or a barbecue that wants to talk about Salesforce stuff, just trust me.” Years go by, he goes to parties and nothing happens, and then he finds you and he just says something. You’re like, “Yeah, that sounds good.” “What?”

Jonathan Fox:
His significant other and mine at the time were just sick of hearing about what is Salesforce? It’s all we spoke.

Mike:
You two go off, grill a burger, talk Salesforce.

Jonathan Fox:
Come back later.

Mike:
Come back later. That’s crazy. So when we talk about data, every single feature that we roll out, it always comes back to data, but I think more so with Agentforce. Now we have to go one layer deeper with metadata, and I’m going to start off with a hard question.

Jonathan Fox:
Go for it.

Mike:
I think it’s hard. How do you know your metadata is bad metadata?

Jonathan Fox:
I think that’s a really good question, and I think it is a hard question. I think it’s really difficult to know whether your metadata is bad, and until you start poking around with things such as AI, you probably don’t realize it. And a really good example, and probably one that we’ve had conversations in the past about this at your org that you use and things like that where you have these field names. Field labels for example is a type of metadata, and they often have acronyms or naming conventions that only you, the users, actually know about. And until you start trying to make AI understand what they mean, you don’t realize because you’ve got all your industry knowledge, you’ve got all your organization knowledge, you’ve done your onboarding. You know how the org works because you’ve been trained and taught and you speak the lingo, but the AI doesn’t know that.

So it’s only until you start getting to play around with these kinds of things, you go, oh, actually, a fresh set of eyes, somebody who has no idea about this hasn’t got a clue, and I think it’s at that point you start realizing our metadata needs to have a little bit of a revamp.

Mike:
Yeah, the field labels and values that you use for fields that are going to be displayed on a page is one thing. I always got quite cavalier, I’ll use the term, with fields and labels for stuff that I just needed on the object that wasn’t going to be displayed on a page. And now I’m thinking, oh God, Agentforce is going to have reference those and it’s totally not going to understand what SP_25Z_PRD means.

Jonathan Fox:
Exactly, but you know what it means?

Mike:
The whole organization knows what it means, because everybody’s into acronyms, and I just need to store the value on the object for the record but I didn’t need to display it for the user, but now I’m going to ask Agentforce for what’s the speed record number or something, and it’s going to look at me like, “I don’t know. You’re not capturing that. I’m going to go back over here and talk with this dude about some Apex and grill a burger.”

Jonathan Fox:
Yeah, exactly. There are ways we can get around it with Agentforce and it’s things like putting those acronyms in instructions, but is that really the best way to do it? That’s almost like hard coding references within Apex. And at that point, you start thinking, yeah, this isn’t right. This isn’t the best way to do it, and I think that probably answers your question. At that point, when you start having to do workarounds and figure things out like that, you know your metadata is not in a good state.

Mike:
So that feels like we’re walking down a path and we hit a fork in the road where we realize there’s a whole bunch of these weird fields. They always include underscores. Why is that? I don’t know. People like the underscore. They do that on Instagram too. Do we create this massive dictionary and feed it to Agentforce, or do we have to go back and… When we talk about clean data, you extract the data, you look at it, you fix what’s wrong and you shove it back in for the most part, or should we do that with metadata?

Jonathan Fox:
I think you have to take a pragmatic approach with anything that you do in the Salesforce org, and that goes for metadata, data, tidying up your flows or refactoring your Apex classes and methods. You take a look at it and go, how big is the job? You impact SS? You go, how big is the job? What’s the return on investment of me doing this now versus the cumulative over the next few years? Is it worth my time to go back and fix it all? And gold standards, what we teach and what we hope to aim for is yeah, go back, refactor it, make it perfect, but sometimes it’s not an issue until it becomes an issue. In this case, for example, your field labels, they weren’t an issue in the past, they are now, and I think it’s one of those where you have to sum up all those different variables and think, is it worth it?

Now, if it’s only a couple of fields and it’s only ever going to be a couple of fields, maybe it’s quick enough just to go back and fix it, or maybe it’s not worth the effort and you write it in the instructions. But I think it’s org dependent, variable dependent, even individual skill set dependent. But it’s one of those that you have to… It’s a really non-answer, I know that, but I think there are so many variables. You can’t just blanket rule. Obviously, we want to aim for gold standard.

Mike:
Well, the fallacy is we hear metadata and data and you think, “Well, I’m just cleaning data.” But the cleansing of it is actually very different, so what are the implications? I’m sure Chris and I will talk about this, but if you go through your org and you’re like, well, everybody has to have a proper name, and so you fix all the nicknames or shortened names. And so you come across the John Fox record. You’re like, nope, it’s got to be Jonathan. I can confidently say for the most part that changing John to Jonathan isn’t going to fire anything, isn’t going to break anything, but my question to you is if I go in and I change a field label or I change some metadata on a field, what could I break?

Jonathan Fox:
Oh yeah, you are risking breaking things. You’re potentially risking breaking your flows, your Apex, your validation rules. Sometimes, hopefully you referenced them through API names and we might not be changing them here. We’re probably changing field labels, not API names, but you may want to change those as well, and then at that point, you are potentially impacting all of your automation in the org, your validation rules, your assignment rules, et cetera, et cetera. So you have a big knock-on effect by changing metadata, and that’s because metadata in Salesforce is the replacement for you writing code on the back end. That’s the whole point of it. That’s why it’s a SaaS and a PaaS to some degree. Salesforce themselves by producing the platform is saving you having to write how fields appear on the UI. You are just putting placeholders there and that’s what metadata is on the Salesforce platform, and you change that, you’re impacting everything else that references it potentially. So there are big consequences and it isn’t just a case of going to object manager and going switch some characters around to make it look neat for Agentforce.

Mike:
So I think oftentimes, people hear cleaning data and I’m sure cleaning metadata, which feels like next level cleaning. It’s like having your carpet shampooed. It’s like, cleaning your house is just vacuuming. Nope, we’re calling in Stanley Steamer. They’re going to do the rugs now. They’re going to get all of the dirt out. It can feel like, oh, we have to do all of it. We have to clean everything. And I don’t know, maybe you have a tiny house and you can spend half a day and clean your whole house. I can’t clean my whole house, but people for some reason look at, “I have to clean all of my data.” Given the implications of updating information and metadata, how should people approach cleaning or getting their metadata right for Agentforce?

Jonathan Fox:
There’s probably a couple of ways to approach it. I have a small house, I can probably clear most of mine within a day so I’m lucky. That doesn’t mean I enjoy it though, so there are definitely-

Mike:
No. Well, there’s that. I don’t know, using the big leaf blower, I could probably clean my whole house and I wouldn’t enjoy it, but it’d be clean.

Jonathan Fox:
Well, that’s true, and it’d be good fun in the process. I suppose if you think you’re going to have guests over to your house, you’re going to host a dinner party or just have some friends, you don’t go cleaning all the bedrooms necessarily, and you clean the places that they’re going to see. You clean your living room or your kitchen and the bathroom that they’re going to use. In a similar way, what is Agentforce going to be using within your org? You might be rolling out Agentforce for a small use case first to prove the ROI to your org. Fantastic. So you might have a small use case and it’s only referencing fields on the contact object. Start with the contact object then. Start with those fields that Agentforce is going to be using, and you’ve proven out that return on investment, your organization loves it, and now they want to expand it to using data from opportunities or orders or whatever else. Then you start moving out to where your guests, your agent, is going to look next.

So that’s how I would personally approach it, is start with what it’s going to be looking at first, because otherwise you’re going to be overwhelmed with such a huge task and that’s not going to be as productive. Be iterative, work on it in chunks, break it down.

Mike:
No, I like that. Clean where the guests are going to be, close the doors to the rest of the house. There’s nothing there.

Jonathan Fox:
Exactly.

Mike:
It’s a doorway to a big black hole. Don’t open that.

Jonathan Fox:
You don’t need to look in there. You don’t need to see the piles of boxes.

Mike:
Here be dragons. So one thing, and I’m going to have to ask Chris this when we record his podcast, because I’ve done data cleansing exercises before where you look at things and consultants, you’re brought into jobs and stuff, and you look at the data and you’re like, well, this is close date and there’s July 27th, 2025. That’s a valid close date. Why is that bad data? And it’s bad data because the process is, well, but after the opportunity closes, we also have an implementation stage and blah, blah, blah, and so if we ask Agentforce, what’s the close date? It should say August 24th because it’s always a month after the close date of the opportunity. How do you know when you’re looking at metadata in the same way that you’re like, oh wait, this is something that Agentforce can’t use, although it completely looks like usable metadata.

Jonathan Fox:
I guess you have to almost treat the agent as it is your employee. It’s your agent employee within your org, but it’s one that hasn’t gone through on board and it doesn’t work day to day in your org doing all the different processes that your service agents or sales reps might be doing. So you’ve got to look at it and treat it as if it is a brand new fresh employee that hasn’t been through any of that training, hasn’t gone through any of that. Straight out of college or something, never been in the industry either, and walk through the life of what you’re asking that agent to do, and if it can’t do it, then that’s where you need to be looking at changing that metadata, change that label.

And you’ve also got to think as well, you don’t necessarily want to change it if it’s going to impact all your human employees either, so where do you draw the line and strike the balance between making your metadata perfect for agents, AI agents, and making it really confusing and changing it all after many, many years for your human employees? And I think there’s a balance that needs to be struck there.

Mike:
So that to me sounds like the importance of perhaps a data dictionary or just org documentation, right?

Jonathan Fox:
Absolutely.

Mike:
We can upload those as resources. I think that’s getting better. I haven’t done it. Have you done that?

Jonathan Fox:
I’ve played around with it a little bit and I think it’ll only get more powerful, and I think it only really highlights the absolute need to have strong documentation within your Salesforce org. Again, documentation is one of those really good topics that we can speak for hours about because documentation is only as good at the point in time when it’s written because your org is ever evolving. As soon as you bring out a new field, you’re having to update that documentation, so keeping on top of it is really important, and trying to have that living document, you upload it to Salesforce for Agentforce to use, it comes out of date immediately. So again, that’s a whole topic of its own, but I think it does really highlight to Salesforce customers and people working in Salesforce orgs that tracking all these kind of things is really key if you haven’t already done it, and that is a big task, but it will pay dividends.

Mike:
Yeah, I think sometimes people, and myself included, you get caught up in the speed and the immediacy at which you can do things and you forget, oh, I need to, best practice, write down what I created, why I created it. So I want to pivot off that because if you have bad metadata, it could be the result of you have a bad deployment process or a bad, I don’t know, requirements or discovery process. Can both be true?

Jonathan Fox:
Yeah, absolutely. If you think all the way back to the beginning of their future and you’ve got your BAs looking into what the product owner wants and they’re trying to gain this information from them and then perhaps translate it into Salesforce terms, and maybe there’s a gap there or maybe the Salesforce consultant hasn’t poked enough holes in the requirements and tried to transform them a bit more. You may have missed that gap all way at the beginning. Or it may be it’s absolutely fine for what you’ve been requested to do and you’ve built it exactly to spec, but it gets to UAT, and at that point, it was missed that your users had no idea or your agentic employees had no idea what it was doing and it got deployed.

And absolutely, that whole lifecycle of development there, there are different quality control gates that absolutely could have missed this or just never had to think about it in the past, and now we do have to think about it. And I heard you laugh a little bit then about the agentic employees and the UAT. Is that something that we maybe need to start thinking about? Testing in UAT, but with agentic employees rather than just running scripts to test things, and taking it outside of the box a little bit. If we’re going to treat them as employees then perhaps that’s the right stage for them to get involved in a different way.

Mike:
Until you said that, I never thought about UAT for agentic employees, but it completely makes sense. And it completely makes sense you can do it with user testing because you don’t want to get all the way to production and then suddenly it falls on its face so you’re like, wait a minute, how come that didn’t work? No, it’s fascinating concept. I think one of the things you mentioned that I want to bring up, so when we have Chris on next week and we talk about data cleansing, I’m going to ask him about changing data. Because data, for everybody, they see it, it’s very visual. If you change the date format, let’s say, of a field and you go from European style to American style, your user is going to be, “Whoa.” They’re going to immediately see that. I don’t know that they would immediately see, or they probably shouldn’t unless they’re pulling in weird fields and reports, metadata fixes.

But with that, I think what is important to get in terms of sign-off or process or executives to go through this process? Because at some point, you’re going to have to talk, well, we got to fix this data, we got to do this, we got to do that, and we need to make sure that we’re fixing the process. I think data is a public thing, your users see it, but metadata is almost the behind the scenes. How do we make the backstage cleaner, and then how do we make sure that all the stagehands know to keep the backstage cleaner? So that’s a really long question of in addition to knowing we need to fix it, if I’m sitting here saying, “Cool, I’ve listened to this podcast and Jonathan’s hammered it into my head, I need to fix it,” who should I start talking to? What are the sign-offs I should get?

Jonathan Fox:
Yeah, I think you are obviously going to need sign-off. You’re going to need the buy-in of the people who hold the budget within the organization, and that could be all sorts of different roles within your organization to all sorts of different levels. I don’t know who that will be in your given organization, but it’s whoever owns the platform ultimately and whoever has the budget to deploy the team who’s going to do, one, the analysis, but two, the actual development, we’ll call it the implementation and the testing and deployment afterwards. And I think the best approach for that is to even perhaps try using Agentforce today without changing your metadata, in a sandbox or something, and then show even the smallest of change and how it impacts the agent. Because listening to the podcast today and hearing that you need to transform your metadata isn’t going to get the sign-off and the approval of these people within the organization.

They’re going to want to see how it changes, why, the metrics behind it, and I think that’s the best way to do it because every org is so different. Your metadata is going to be so different from the org next to yours, there is no one rule fits all, and I think other than just showing and visually demonstrating how much Agentforce can enhance your org without it versus with the change and show how much it can speed up your users and all the automations it can do, I think that’s the best way to approach it, and it is with that person who ultimately holds the budget.

Because it’s not a one-person job. There is going to have to be some analysis there. You’re going to have to do some changes, you’re going to have to test them and deploy them. It’s almost a project in itself, and I think it should be treated as such because it is such an important step. And your metadata is the foundations of your Salesforce org. You don’t want to get it wrong, you don’t want to make it worse, so it needs to be treated with that respect and that importance when you’re changing it.

Mike:
Well, if you think of it, I’ve always answered the question, if you ask a company what’s its most valuable asset, it shouldn’t be the product it puts out. It’s the data that it has, and its second most valuable is its metadata because that’s the way that you find out what data you have.

Jonathan Fox:
Yeah, exactly.

Mike:
And you query it.

Jonathan Fox:
Yeah. If you don’t have a strong metadata structure within your Salesforce org, well, then you don’t really have a Salesforce org because your data’s not going to fit. So yeah, it’s second because obviously the data is what you’re using day-to day. That’s the valuable part.

Mike:
One thing we haven’t touched on is we’ve lived in this perfect world of we’re just fixing metadata in Salesforce. I don’t want to say the wrong term, but when I think about it, integrations, I call it the data you inherit, the data that comes from other systems. How should we approach metadata fixes for that?

Jonathan Fox:
It’s difficult, especially if you’re forced into a particular route because of an integration or another system, but the Salesforce platform is really flexible. There’s not really any reason why the metadata that Agentforce uses today can’t be specific and clean in accordance with your Salesforce org. There is no other external system out there that necessarily will force you down a rabbit hole and make you have to do it in a certain way. There are always ways that within the org, you can transform your data from where it’s held on that metadata and make it work for those external systems.

I think it goes back down to again though, making sure your documentation’s clean, because if you are forced down a particular route through inherited metadata or third party systems and all the things that you can’t control perhaps, then that’s where the documentation becomes vital again as we mentioned earlier.

Mike:
Yeah, especially if you’re… Anytime you bring something in or Salesforce pushes data out, there has to be some documentation on that. That was always the fear that I had as an admin of did I leave enough behind so that somebody knows if things go thermonuclear, what buttons to push? And the end result is if you feel like you have enough, you’re probably halfway there because you could always write more.

Jonathan Fox:
Yeah, absolutely, and even look at the things that you can’t control. You have some really cool app exchange apps in your org. You can’t control their metadata. That’s the whole point of those vendors, and perhaps they’re not top of mind for AI at the moment or they’re getting round to doing it, but you want to adopt it before they’ve had chance. That’s where documentation is going to become key, because you can’t control what they’ve produced for your org, and it works amazingly because it’s the product you’ve been using for years. But you need it to work today for Agentforce and perhaps they’re not ready or it doesn’t work the way that you want it to but it works for them and all their other customers. Documentation is going to be a key there.

Mike:
Right, absolutely. Well, this is fun. We dove into the scenes behind the scenes. It’s like best practices on writing cue cards for comedians.

Jonathan Fox:
Absolutely.

Mike:
It’s the person that stands behind the camera that tells the camera and the comedian what to do is often underappreciated. There’s a whole world of people, just to go off on a tangent, that do write cue cards, and there’s a script to learn how to write it so that it’s very readable. It was a fascinating-

Jonathan Fox:
I did not know that was a thing.

Mike:
A fascinating little rabbit hole I went down one day on YouTube and the internet, because you can learn everything from the internet these days.

Jonathan Fox:
Oh, it’s so true.

Mike:
Yeah, isn’t it? But you’d think by now we’d be printing it, but nope, it’s humans writing it. So Jonathan, this was a blast. I’m glad we came on, we got to talk about metadata. I think it’s probably the thing that most people aren’t looking at. They’re probably like, “Oh, I got to fix my data. I got to do this,” and they’re just tidying up the entryway and they’re forgetting there’s a whole lot more to do behind the scenes in addition to just the data that Agentforce consumes, and it pays dividends outside of that too. Better reporting, better everything. I know that I’m guilty of users running reports and including fields and them saying, “I don’t know what it is, but I just included it because it had numbers in it.” I’m like, cool.

Jonathan Fox:
Because it makes the report look fancy.

Mike:
I need to fix that field and make it a little bit better. But no, this was great. Thanks for coming on the podcast.

Jonathan Fox:
Yeah, thank you for having me. I’ve really enjoyed it.

Mike:
Big thanks to Jonathan Fox for joining us and breaking down the realities and opportunities of cleaning up metadata, and as Agentforce becomes part of the how we work, taking a closer look at what’s under the hood of our orgs is more important than ever. Now, before I say that and you’re this far, get ready for next week’s episode because in addition to cleaning metadata, I’m going to talk with Chris Emmett about cleaning data, and this is a super fun episode. We do go off the rails a little bit about movies, but that’s okay. So I hope you enjoyed this episode. I hope you take the time, listen to what Jonathan has to say, talk to your executives, your stakeholders about field labels, documentation habits. And if you loved what you hear, share it with a fellow Salesforce admin, tweet it out on social, and until next time, we’ll see you in the cloud.

The post How Should I Clean Metadata for Salesforce AI Agents? appeared first on Salesforce Admins.