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. aprity supports multi-org documentation on Professional (up to 3 orgs) and Enterprise (unlimited) plans.

Understanding Multi-Org Support​

Each Salesforce org connected to aprity is treated as an independent documentation target:

  • Separate registration -- Each org requires its own installation and registration of the aprity managed package.
  • Separate scan history -- Scans, results, and feedback are scoped to the individual org.
  • Separate documentation sets -- Generated documentation is stored per org, with no cross-contamination.
  • Shared tenant -- All orgs under the same aprity account belong to the same tenant, which determines the plan and feature entitlements.

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 distributing documentation to stakeholders:

  • Label all documentation with the org name and scan date.
  • Store documentation in org-specific folders if downloading locally.
  • Use the Doc Browser in each org's aprity installation for online access.

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
Starter1Document production only
ProfessionalUp to 3Production + 1-2 key sandboxes
EnterpriseUnlimitedProduction + all relevant environments

Scan quota management​

On Professional plans with 2 scans per week across 3 orgs, plan your scan schedule carefully:

  • Dedicate most scans to production (weekly).
  • Scan sandboxes on-demand before major deployments.
  • Use scheduled scans for production and manual scans for sandboxes.

On Enterprise plans with daily scans per org, you have more flexibility:

  • Schedule daily scans on production.
  • Schedule weekly scans on active sandboxes.
  • Run manual scans on other environments as needed.

Multi-Org Governance​

Assign org owners​

Designate a documentation lead for each org:

OrgOwnerResponsibility
ProductionSenior AdminWeekly 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.