Skip to main content

Multi-Org Documentation Strategy

Organizations running multiple Salesforce orgs need a clear strategy for which orgs to document, how to organize outputs, and how to compare documentation across environments. Each aprity plan covers a single Salesforce org -- one tenant maps to one org. "Multi-org" therefore means running a separate aprity registration (a separate tenant) per org. Contact sales@aprity.ai to set up additional registrations.

Understanding Multi-Org Support​

Each org you document gets its own aprity tenant, treated as a fully independent documentation target:

  • Separate registration -- Each org requires its own installation and registration of the aprity managed package, producing a distinct tenant.
  • Separate scan history -- Scans, results, and feedback are scoped to that org's tenant.
  • Separate documentation sets -- Generated documentation is stored per tenant, with no cross-contamination.
  • Per-tenant entitlements -- Each tenant has its own plan and feature entitlements; there is no shared org pool within a single tenant.

Which Orgs to Document​

Production orgs​

Production is the source of truth for your business processes. Always prioritize documenting production orgs because:

  • Production contains the live business rules and automation that affect users and customers.
  • Compliance audits require documentation of production configurations.
  • Stakeholders reference production documentation for business decisions.

Sandbox orgs​

Document sandbox orgs when:

  • Pre-deployment review -- Run a scan on a full sandbox after deploying changes to preview how documentation will change before promoting to production.
  • Development documentation -- Developers working on complex automation benefit from up-to-date documentation of the sandbox they are developing in.
  • Training environments -- If you maintain a dedicated training sandbox, documenting it helps trainers keep materials current.
tip

Use sandbox documentation as a preview mechanism. After a major deployment to sandbox, run a scan and compare the output against production documentation to understand the impact of your changes.

Developer orgs and scratch orgs​

Documenting developer orgs or scratch orgs is generally not recommended because:

  • They contain incomplete configurations.
  • They change frequently and unpredictably.
  • Scan quotas are better spent on production and stable sandboxes.

Organizing Documentation Across Orgs​

Naming conventions​

Use clear, consistent scan names that identify the org:

  • Production - Monthly Scan - April 2026
  • UAT Sandbox - Pre-Release 2.5
  • Training Sandbox - Q2 2026 Refresh

Documentation distribution​

Maintain separate documentation sets for each org. When sharing documentation with stakeholders:

  • Label all documentation with the org name and scan date.
  • Share deep-links from the aprity web portal scoped to the correct org's scan.
  • Use the portal's scan picker to navigate between past scans for any given org.

Comparing Documentation Across Orgs​

Pre-deployment comparison​

To understand how a deployment will affect your documentation:

  1. Run a scan on production to capture the current state.
  2. Deploy changes to a full sandbox.
  3. Run a scan on the sandbox with the same object selection and configuration.
  4. Compare the outputs to identify documentation changes.

This is particularly valuable for:

  • Identifying new business rules introduced by the deployment.
  • Detecting changes to existing automation.
  • Reviewing the impact on process documentation.

Production vs. sandbox drift​

Over time, sandboxes can drift from production due to:

  • Incomplete refreshes.
  • Development work that was never promoted.
  • Configuration changes made directly in the sandbox.

Comparing documentation between production and sandbox helps identify configuration drift and ensures your sandbox accurately reflects production.

Plan Considerations​

PlanConnected OrgsBest Strategy
Trial1Document production only
Documentation1Document production; use scan budget for key sandboxes
Intelligence1Production + key sandbox; use 7 scans/week budget flexibly

Scan quota management​

On Documentation plans with 1 scan per week, plan your scan schedule carefully:

  • Dedicate the weekly scan to production.
  • Run manual sandbox scans before major deployments.
  • Use scheduled scans for production.

On Intelligence plans with 7 scans per week, you have more flexibility:

  • Schedule daily or bi-daily scans on production.
  • Reserve budget for on-demand sandbox scans around deployments.

Multi-Org Governance​

Assign org owners​

Designate a documentation lead for each org:

OrgOwnerResponsibility
ProductionSenior AdminRegular scans, feedback review, compliance
UAT SandboxRelease ManagerPre-deployment scans, change comparison
Training SandboxTraining LeadPost-refresh scans, training material updates

Coordinate feedback across orgs​

Feedback submitted in a sandbox does not carry over to production (and vice versa). If a reviewer identifies an issue in sandbox documentation that also exists in production:

  1. Submit feedback in the production org's aprity installation.
  2. The next production scan will incorporate the correction.