Documentation quality and accuracy standard

Use this standard for every page in docs. Create your first Check is the administrator-task reference for Setup labels, ordered steps, expected results, and recovery. The Batch Apex guide is the developer-task reference for complete code and explicit decisions. Match their clarity, but use the page structure that fits the reader’s task. An installation guide, worked example, metadata reference, and Apex guide should not have identical sections.

Review documentation changes with this contributor standard. Keep it in contributor navigation so administrator task paths stay focused on product use.

Prerequisites

Before editing one page:

1. Read that page from beginning to end without editing it.
2. Follow its local links and identify information that the reader must understand on the current page instead of behind a link.
3. Verify technical claims against the current package source, configuration, release file, or script that owns the behavior. Do not use another documentation page as the only proof.
4. Read the task or technical reference page that covers the same Salesforce operation.
5. Edit and validate this page before starting another page.

Confirm exact Setup labels, API names, defaults, supported values, limits, permissions, method signatures, returned IDs, and result behavior. If the repository does not prove a claim, do not guess.

Step 1: Write for a Salesforce administrator first

Open with the Salesforce task, decision, or lookup the page supports. When code, hosted services, or restricted support access is required, say so directly and link to a no-code task when one is available.

• Start with the Salesforce task the reader wants to complete.
• State the useful outcome directly. Skip narrated openings such as “On this page” or “This guide.”
• Name sections for the action, scope, or result they contain. Prefer Resolve verification issues to If verification fails and Component scope to What the component is not.
• Keep exact labels such as Failure Severity, System Error, and Error Log when they match Salesforce Setup, card output, an API contract, or a troubleshooting result.
• State limitations and prohibited actions when they protect data, access, package integrity, or a reliable result. Give the reader the approved path in the same section.
• Use familiar Salesforce terms such as record, Flow, Apex job, Permission Set, Custom Permission, Platform Event, and Qualified API Name.
• Introduce a technical term only when the reader must see it in Setup, Flow Builder, Apex, an error, or monitoring. Explain it where it first appears.
• Do not use internal engineering terms when normal Salesforce language says the same thing.
• Do not organize documentation around assumed roles or team structures, and do not use unexplained sample variables.

Keep internal review material out of user guides

Installation guides, examples, FAQs, and public API references must help the reader use the product. Do not publish editorial scoring tables, ratings of example quality, draft approval questions, or instructions to the author or reviewer in those pages. Published example tables describe the available configuration, so label their entries Value, not Proposed value.

Keep package release procedures and contributor checks in contributor or maintainer documentation. Link to those from contributor navigation. Keep internal review findings in local review evidence. Expected Check results, instructions for testing a configuration, and business scores calculated by a Check belong in user documentation when they help the reader complete the task.

npm run check:docs rejects known internal-review phrases in user pages. Passing that check or the structural audit does not establish usefulness or reader fit. Review every paragraph and table for what the reader needs to do or understand, including text that matches none of the automated patterns.

Keep setup guidance current

Keep setup guidance current across releases. Refer to the latest released package through the stable installation links and release configuration. Link tool prerequisites to the toolchain configuration instead of repeating version numbers. Do not pin a public walkthrough to a package ID or source commit. Keep exact release history in the changelog and machine-readable configuration. When a command needs a package ID, explain where to obtain it and use a clearly named placeholder. Keep source examples and their data scripts together so that removing a version number does not imply an unreleased feature is already available in the installed package.

Use the right page order

For a task guide, use these sections when they apply:

1. A title that states the outcome.
2. A short introduction explaining when and why to use the API.
3. Concrete examples labeled Example:.
4. Before you start, including access, Qualified API Name, record limits, and result handling.
5. Complete steps in the order the reader performs them.
6. Complete code with comments explaining package names, inputs, result choices, and returned IDs.
7. A plain-language explanation of every code argument and output that is not obvious.
8. Monitoring, testing, troubleshooting, and related guides.

Do not place a test or scheduling step before the class it uses. Define a sample class once and reuse it instead of showing competing versions of the same class.

For other page types:

• A worked example starts with a familiar Salesforce requirement, explains why its Evaluation Type fits, shows every configuration value, states what the user sees, and includes positive and negative tests.
• An installation or operations guide states prerequisites, gives ordered steps with expected results, explains how to verify the change, and provides recovery steps when it fails.
• A metadata reference uses the exact Setup label and API name, explains what the field changes, gives its default and allowed values, and links to a task guide that shows when to use it.
• A technical reference defines the contract precisely, separates public behavior from internal implementation, and gives examples only where they make the contract easier to apply.
• A folder overview helps the reader choose a page by Salesforce goal. It does not merely list filenames or repeat every child page.

Keep independent decisions separate. For a background job, distinguish how records are selected, when the job starts, how many records run in one transaction, and where results go. When one complete example combines those choices, list the selected values and state that they are example choices rather than universal recommendations.

Give every user task one owner

Each supported user job must have one primary maintained page. Update that page when behavior changes instead of adding a second end-to-end procedure elsewhere. Folder indexes and the documentation home route readers to the owner; reference pages can supply exact field, API, event, or reason-code contracts without becoming competing walkthroughs.

Before publishing a new task guide or materially changing an existing one:

1. identify the current owner page and reconcile overlapping procedures;
2. verify the complete path with the permissions and environment named by the guide;
3. prove the expected outcome and at least one relevant negative, fault, or access outcome;
4. exercise the documented troubleshooting and recovery or cleanup path; and
5. update the owning folder index and primary navigation when discoverability changes.

Production installation, upgrade, uninstall, external event delivery, Agentforce, and hosted MCP procedures require an approved representative environment and owner. A desk review or passing link check does not replace that runtime walkthrough. Record any unverified environment-specific claim as a limitation instead of presenting it as completed evidence.

Make Salesforce names unmistakable

Label names by their purpose:

• Permission Set: Record Health Check Card User
• Custom Permission label: Record Health Check Run
• Custom Permission API name: rhc__Record_Health_Check_Run
• Check Set Qualified API Name: My_Account_Checks

Explain that rhc. identifies a packaged Apex type and rhc__ is the namespace prefix on an API name delivered by the installed package. Tell readers to copy the exact Qualified API Name from Setup and never add or remove rhc__ themselves.

Make examples safe to follow

• Use an administrator-created Check Set such as My_Account_Checks in active code.
• Mention an installed-package name such as rhc__Example_Account_Check_Builder_Guide only as an alternative in a comment or explanation.
• State where every sample variable comes from.
• In Setup examples, give the complete navigation path and use the label the administrator sees.
• In Custom Metadata examples, separate the field label from its API name.
• When example custom objects or fields are required, say that they are not included with Record Health Check, list what must be created, and warn that the code will not compile first.
• Use comments to explain NONE, ACTIONABLE, and ALL where the publication argument appears.
• State whether a returned ID identifies a scheduled job, Apex job, Record Health Check run, or Salesforce record.

Explain results before monitoring

Always distinguish these outcomes:

• PASS, FAIL, SKIPPED, UNABLE_TO_EVALUATE, and ERROR are health results.
• Setup → Apex Jobs shows whether an Apex job completed; it does not show individual health results.
• FAIL means a record did not meet a Check. It does not mean the Apex job failed.
• Platform Events are messages, not permanent storage. A Flow, Apex trigger, or integration must receive them.
• NONE is useful when custom code reads and saves the returned response directly. With a packaged background class that returns only a job ID, NONE retains no individual health results.

State limits as decisions

Do not list a limit without explaining what the reader should do:

• State the allowed value.
• Give a starting value.
• Explain when to lower or raise it.
• Keep the total record limit separate from the number processed in one transaction.
• Use a numerical example when several limits interact.

Review one page before moving to the next

Before completing a documentation change, read every affected page from beginning to end and ask:

• Can a junior Salesforce administrator identify the correct option without guessing?
• Is every Setup name labeled and every path complete?
• Does each example say where its inputs come from?
• Can the reader tell where results go and where job status appears?
• Are required custom objects, event receivers, permissions, and tests stated before use?
• Does any paragraph repeat code comments without adding useful context?
• Does a link replace detail the reader needs at the current step?
• Are examples and limits consistent with the package source and with every already-reviewed page?
• Does the page use links for optional depth rather than to avoid an explanation needed now?
• Could any sentence be read in two reasonable ways?

Run the formatter and documentation checks for the page. Then read the rendered Markdown structure from title to final link. Only after that page passes should the next document be opened for review.

After every page in a folder has passed individually, reread the folder in navigation order. Remove contradictions and unnecessary repetition, but keep information that a reader needs to use each page without searching another page first.

Verify the generated static site

Markdown is the maintained authoring format, not the browser delivery format. The Astro build must convert every maintained page to usable HTML without exposing Markdown syntax or losing document structure. npm run check:docs:site is a required source gate. After building all pages, it inspects the generated HTML and rejects:

• missing or empty main content and an incorrect number of page titles;
• skipped heading levels or empty headings;
• raw fences, callouts, links, headings, tables, or MDX statements;
• task-list checkboxes without accessible names;
• anchors without destinations; and
• generated undefined or [object Object] values.

This static gate is deliberately fast enough for every CI run. Its regression fixtures include the split-table-row and unnamed-checkbox failures found during the complete 2026-09-26 rendered-site review. Source formatting and link checks cannot substitute for this generated-output boundary.

Run npm run audit:docs:render when a change can affect conversion or presentation across pages, including Astro or Starlight upgrades, Markdown preparation, global components, global styles, navigation, and responsive layout. The command builds the site, starts an isolated local server, captures every route at 1440×1000 and 390×844, and writes a manifest plus review gallery under reports/docs-render-audit/. It also fails on browser errors, failed local assets, broken images, horizontal overflow, and every static-gate finding. Open the gallery and review every screenshot; zero automated findings do not prove that spacing, clipping, overlap, contrast, or reading order is visually correct. Keep the report as local evidence and record the command and result in the pull request when this audit is required.

Troubleshooting the review

If a documentation check fails, correct the page structure or broken statement instead of weakening the check. If source behavior is unclear, stop and verify the Apex implementation before describing it. Do not guess at a permission, limit, object, field, return value, or Setup path.

Carry verified lessons into the owning guidance

When a review or runtime test disproves a claim, update the page that owns it and every affected example, API contract and contributor rule. Record the input, observed mismatch, corrected behavior, named regression and remaining evidence boundary. A passing formatter or link gate does not verify that a limit, method, fallback, permission or instruction is true.

Keep reusable implementation and testing rules in the regression testing standard, with short pointers from AGENTS.md. Feature-specific decisions belong in the local specification; org identities, ownership and local reporting limitations belong in internal agent notes. Keep session chronology and historical findings in evidence, visibly superseded where necessary, rather than copying them into user walkthroughs.

Review examples for complete callable signatures and required methods. Mark excerpts as excerpts. Distinguish business results from test/job outcomes, optional display from evaluation, per-field from request limits, and source behavior from installed-package availability. Do not convert a planned procedure, source inspection or live API test into a claim that the browser journey was verified.

Related

• Source development
• Documentation home
• API documentation
• Batch Apex reference example