Docs design standard

Docs design standard

PowerAdvice CMS documentation is written for Tory and LeeAnn first. Each page should help an operator finish a real CMS task without asking BFD to translate fields, states, or recovery steps.

Screenshot standard

Screenshots must show a representative workflow state, not a blank landing page. A useful screenshot includes:

• the left navigation section;
• the selected record or workflow tab;
• the field group that matters for the decision;
• safe synthetic content that reads like PowerAdvice work;
• no production subscriber data, personal contact data, cookies, Access tokens, Clerk state, or secrets.

Use UAT first and staging second. Do not capture production for docs.

Callout standard

Use callouts to reduce risk, not to decorate the page.

Callout type	Use when	Example
Decision	the operator must choose between states or workflows	Draft vs. Staged vs. Published
Warning	a mistake could publish, remove, expose, or misroute content	do not bulk-publish migrated articles during review
Recovery	the operator needs a safe backout path	unpublish, verify, correct draft, republish
Evidence	a public URL, preview, or status proves the change worked	live article route renders the expected title

Task-card standard

Every major workflow should answer these questions near the top of the page:

1. What am I trying to do?
2. When should I use this page?
3. Which fields matter most?
4. What should I avoid?
5. What proves the task worked?
6. What do I do if it breaks?

Decision guidance

Write state decisions in plain operator language:

• Draft: private work in progress.
• Staged: reviewable link or AI-review state, not public/indexed launch content.
• Scheduled: approved content waiting for a future publish time.
• Published: live public content.
• Unpublished or archived: removed from public flow but recoverable.
• Deleted: permanent cleanup path only when explicitly approved.

Recovery language

Recovery steps should be calm, specific, and reversible:

1. Stop public exposure if needed.
2. Verify what changed.
3. Correct the CMS record.
4. Preview the corrected state.
5. Publish only when the owner approves.
6. Capture enough detail for BFD if the issue repeats.

Do not blame the operator. Name the record, route, field, state, and expected result.