Skip to content

Troubleshooting Authoring Template

This page contains copy-paste patterns for adding troubleshooting and quick-check content to documentation pages. It is intended for internal use by documentation authors.

Pattern A: Quick Check (Collapsed Tip)

Place near the top of a page, after the overview, before procedural steps.

??? tip "Quick Check - Before You Start"

    - Ensure you have **Admin** or **Manager** permissions
    - Verify the relevant module is enabled in **Site Settings**
    - Confirm your browser is up to date

Rendered preview:

Quick Check - Before You Start
  • Ensure you have Admin or Manager permissions
  • Verify the relevant module is enabled in Site Settings
  • Confirm your browser is up to date

Pattern B: Common Pitfall (Expanded Warning)

Place inline, immediately before or after the step it relates to.

!!! warning "Common Pitfall"

    If the import fails silently, check that your CSV headers exactly match
    the template column names (case-sensitive).

Rendered preview:

Common Pitfall

If the import fails silently, check that your CSV headers exactly match the template column names (case-sensitive).

Pattern C: Troubleshooting FAQ Section

Place at the bottom of a page under a ## Troubleshooting heading. Use collapsed question admonitions.

## Troubleshooting

??? question "Why is [feature/item] not appearing?"

    Brief explanation of the root cause.

    **Steps to resolve:**

    1. Navigate to **Module > Section**
    2. Check the relevant setting or filter
    3. Apply the change and verify

??? question "Why does [action] produce an error?"

    Describe the cause and any pre-conditions that trigger this.

    See [Related Page](../path/to/page.md) for more details.

Rendered preview:

Why is [feature/item] not appearing?

Brief explanation of the root cause.

Steps to resolve:

  1. Navigate to Module > Section
  2. Check the relevant setting or filter
  3. Apply the change and verify
Why does [action] produce an error?

Describe the cause and any pre-conditions that trigger this.

See Related Page for more details.

Admonition Type Quick Reference

Type Keyword Use For
Tip tip Quick checks, pre-requisites, "before you start"
Warning warning Common pitfalls, gotchas, data-loss risks
Question question Troubleshooting FAQ items (collapsible)
Info info General helpful information
Note note Supplementary context or clarifications
Danger danger Critical warnings (security, irreversible actions)

Always use lowercase keywords. Never use tips, Notes, Note, or warnings.