How to document a Salesforce org

Start with a decision, not a metadata dump

Salesforce org documentation describes the configuration of a specific organisation: its data model, automations, validation rules, access model and integrations. Salesforce product documentation explains platform behaviour; your org documentation must explain your own configuration and the limits of what you have verified.

Choose an initial purpose: inheriting an org, preparing an audit or reviewing a release. Start with one important process and its owning team. Record the org, environment, extraction date, repository revision and included component types before describing behaviour.

Inventory the data model and its owners

List each in-scope object with its API name, relevant fields, relationships and known owner. Preserve API names alongside business labels so a reviewer can find the original component. Separate a field description found in metadata from a business meaning confirmed by an owner.

Do not label a field unused because no reference was found. Usage, static references and external consumption are different questions, and each needs its own evidence.

Describe automation as conditions and effects

For each Flow, validation rule or Apex entry point, record the event, conditions, reads, writes, calls and exceptions that you can establish from the source. Include the version and activation state where available. Follow subflows and invoked code within your declared scope.

Describe branches separately. For a validation rule, show the condition that blocks saving and examples of passing and failing inputs. Do not invent the business reason for a condition just because its technical effect is clear.

Map dependencies and document blind spots

Use metadata references and code analysis to identify relationships between components. Keep a link to the evidence for each relationship. List external consumers separately: an integration’s configuration may live outside Salesforce.

Dynamic field names, inaccessible managed-package internals and unavailable metadata can leave gaps. Record these as unknown or out of scope. A dependency diagram helps plan testing; it does not certify that a change is safe.

Keep access configuration separate from verified access

Document profiles, permission sets, sharing settings and other relevant access controls. Do not infer a person’s effective access from a single profile or permission set. State which combinations and user scenarios were actually checked, and protect any sensitive evidence.

Review, publish and refresh after changes

Have a technical reviewer check the source traceability and a process owner check the business explanations. Publish unresolved questions next to the relevant section rather than silently filling them in. Record a review date and an owner for the next update.

After a release, refresh the baseline, compare changes and re-review the affected explanations. Documentation reflects the last observation, not necessarily the live org. Keep deployment evidence and executed test results separately.

Where aprity fits

aprity builds a documentation portal from Salesforce metadata, computes dependencies and uses AI to explain the results. This supports inventory, exploration and refresh work. Your team still validates business intent, external dependencies and runtime behaviour. Use the template and worked example below to define what you expect before evaluating a tool.