How to document a Salesforce org so it survives turnover

To document a Salesforce org so it outlives any one admin or partner, record why things exist, not just what exists. Capture the data model, every automation with an owner, and each integration with the user it runs as. Add the security model, key leadership reports, release history and known issues. Keep short descriptions inside Setup, a living runbook beside it, and change history in source control. Then make documentation part of finishing every piece of work.

Why does Salesforce documentation matter more than people expect?

Because the org keeps running after the people who built it leave, and nobody can safely change what nobody understands. Undocumented orgs get slower and riskier to change every year.

Most orgs we inherit share one pattern. The configuration is visible to anyone with Setup access, but the reasoning is gone. A validation rule blocks certain opportunities, and no one knows which business rule it enforces. A nightly job updates accounts, and the integration user behind it belongs to a former employee.

Good documentation answers three questions for any component. What does it do? Why does it exist? Who decides whether it can change? If a new admin or a new partner can answer those without a meeting, the org is documented well enough.

What should you actually document in a Salesforce org?

Seven areas cover nearly everything a successor needs. Start with the ones that cause outages when misunderstood: automation, integrations and security.

• Data model: each custom object and the important custom fields, with the business reason they were added and which team relies on them.
• Automation inventory: every active flow, Apex trigger, scheduled job and remaining legacy rule, with its purpose, trigger condition and a named business owner.
• Integrations: each connected system, the direction data moves, how often, which integration user it authenticates as, and who to call when it fails.
• Security model: profiles, permission sets and groups, org-wide defaults, role hierarchy and sharing rules, plus the reasoning behind any unusual access.
• Leadership reports and dashboards: the handful executives open most often, what each metric means, and which fields feed it.
• Release history: what changed, when, why and who approved it.
• Known issues: workarounds users rely on, accepted limitations and anything deliberately left unfinished.

The "why" column is the part most teams skip. A field list can be exported in seconds. The reason a picklist has a value called "Legacy - do not use" lives only in someone's memory until you write it down.

Where should Salesforce documentation live?

Split it by audience and by how often it changes. Short explanations belong inside Salesforce itself; procedures and diagrams belong in a runbook; change history belongs in source control.

Every custom object, field, flow and permission set has a Description box in Setup. Use it. A one-line purpose plus the requesting team is enough, and it moves with the metadata when it is deployed or retrieved. Help text is different: it is for end users, so keep it free of technical notes.

The runbook is a shared document or wiki page outside Salesforce. It holds anything longer than a sentence: integration failure procedures, the steps for annual price list updates, user onboarding and offboarding, and the list of known issues. Link to it from a utility bar item or app home page so admins can find it.

Diagrams carry what text cannot. An entity relationship view of the core objects and a simple box-and-arrow map of integrations are usually the two most valuable. Schema Builder can help you sketch the data model, though most teams redraw it in a diagramming tool for readability.

If your team keeps metadata in a Git repository, through DevOps Center or another pipeline, commit messages and pull requests become your release history. Write them for a reader two years from now. Confirm the current capabilities of DevOps Center with your Salesforce account team, since its features continue to change.

How do you start documenting an org nobody wrote down?

Inventory first, then interview. Use the tools Salesforce already provides to list what exists, then fill in the reasons by asking the people who use it.

A practical first pass looks like this:

• Open Schema Builder on your core objects to see relationships at a glance and spot objects nobody mentions.
• Download the Setup Audit Trail to see who changed configuration recently. It keeps a limited window of history, so export it regularly; confirm the current retention period in Salesforce Help.
• Run Org Check, a free tool published through Salesforce Labs, to list fields, flows, Apex, permission sets and other components with usage hints. Check the current listing before installing, since Labs tools are not supported like core features.
• On a custom field, use the "Where is this used?" button in Setup to find the layouts, flows and code that reference it. Coverage varies by metadata type, so treat the result as a starting point.
• For deeper dependency questions, developers can query metadata component dependencies through the Tooling API. Check its current limits and supported types in the developer documentation.

With the inventory in hand, book short sessions with each department. Walk through their objects, reports and automation, and ask why each one exists. Write the answer straight into the Description box during the call. Anything nobody can explain goes on a review list rather than being deleted on the spot.

How do you keep Salesforce documentation current?

Make it part of the definition of done. A change is not finished until its Description boxes, runbook entries and release notes are updated.

Add a documentation line to every work item template, and have the reviewer check it before deployment. If you use pull requests, a reviewer can refuse a merge when a new flow has an empty description. Small, steady updates are far cheaper than a documentation project every few years.

Schedule a light review each quarter. Re-run your inventory tool, compare it with the runbook, and flag anything new that lacks an owner. Retire documentation for components you have removed, so the runbook does not describe a system that no longer exists.

What should a Salesforce partner hand over?

Everything your next admin or partner would need to support the org without calling them. Ask for it in the contract, not at the end of the engagement.

A reasonable handover package includes:

• The runbook and diagrams in a location you own, not the partner's workspace.
• Access to the source repository, or a full metadata retrieval if there is no repository.
• A list of integration users, connected apps and named credentials, with where each secret is stored and who can rotate it.
• Release notes for work they delivered, including anything deferred or partly built.
• The open known-issues list and any support tickets still in progress with Salesforce or vendors.

Review the package while the partner is still engaged. Pick two components at random and check whether the documentation lets your team explain them. If it does not, ask for fixes before the final invoice is approved.

Which documentation mistakes cause the most trouble later?

Writing what instead of why, storing documents where only one person can reach them, and letting records go stale. Each one quietly undoes the effort you put in.

• Copying field labels into a spreadsheet and calling it a data dictionary. Labels are already in Salesforce; the business reason is what is missing.
• Keeping the runbook in a personal drive or a partner's tool that disappears when the contract ends.
• Naming owners by job title only. Name a person as well, and update it when they change roles.
• Leaving integration credentials undocumented, so nobody knows which jobs stop if one user is deactivated.
• Writing a large document once and never revisiting it. Outdated documentation misleads people more than a gap does.
• Putting technical notes in help text, which confuses the users who actually read it.

What does a minimum viable documentation checklist look like?

Use it to check whether an org is documented well enough for a handover. If any row is blank, start there.

If the checklist exposes larger problems, such as overlapping automation or orphaned fields, documentation alone will not fix them. A health check or a managed services team can sort out what to clean up versus what to record and keep.