FAQ Content Standard

Purpose: Most FAQ articles follow the same 7-section structure so readers always know where to find the quick answer, the detailed steps, or troubleshooting help. A flexible Reference / Hybrid shape is also permitted for content that mixes information and guidance in one article — see the section at the bottom of this document.

---

Two Page Shapes

Shape	When to use	Required structure
Standard How-To	A single procedural task: "how do I X?"	The 7-section structure below — strict
Reference / Hybrid	Decision guides, comparison tables, error dictionaries, conceptual explainers, or any article that blends information + guidance	Flexible — see Reference / Hybrid Shape at the bottom of this doc

The default is the standard how-to. Only deviate to a reference shape when the strict template demonstrably gets in the way of the content.

---

The 7-Section Structure (Standard How-To)

#	Section	Purpose	Component(s)
1	TL;DR / Quick Answer	The 1-2 sentence answer for busy readers	QuickAnswer (preferred)
2	Problem Statement	One sentence: what question does this answer?	A second QuickAnswer block (intentional — see below)
3	Before You Start	Prerequisites: permissions, tools, prep work	Callout (variant="info")
4	Step-by-Step Instructions	Numbered actions with visuals	Step inside StepFlow
5	Troubleshooting	Common issues & solutions	Step collapsible with icon
6	Related Resources	Links to related FAQs / Wiki	CardGrid + InfoTile (variant="navigation")
7	Author	Who wrote/maintains this	Author component

Note on section order: The TL;DR comes first because most readers only need the quick answer. The Problem Statement that follows is rendered as a second QuickAnswer block (with a title like "What Problem Does This Solve?"). This intentional pattern keeps both pieces visually consistent and scannable, instead of mixing a plain heading with a coloured callout.

---

Section Details

1. TL;DR / Quick Answer

Open with a QuickAnswer — the lightweight, low-noise highlight (coloured left border, no background box). This is what most readers will read.

<QuickAnswer color="green">
  Use <strong>Patient Search → Merge Records</strong> to combine duplicates.
  Always verify the correct master record first.
</QuickAnswer>

Use Callout only when the quick answer needs strong visual emphasis (warnings, critical steps).

---

2. Problem Statement

Render the problem statement as a second QuickAnswer block with title="What Problem Does This Solve?". This is intentional — it keeps the visual rhythm consistent with the TL;DR above and avoids mixing a plain ## heading next to a coloured component.

<QuickAnswer color="blue" title="What Problem Does This Solve?">
  Duplicate patient records occur when a patient is registered more than once in CCMS.
  This FAQ shows you how to identify, verify, and safely merge duplicate records.
</QuickAnswer>

You may also use variant="note" for a softer accent. Avoid plain ## Overview or wall-of-text introductions.

---

3. Before You Start

Use a Callout with variant="info" and a title="Prerequisites". Keep the list to 3-5 items max.

<Callout color="blue" title="Prerequisites">
  - **Administrator or Front Desk** role with patient management permissions
  - The **correct IC number** for the patient
  - Both records must be within the **same clinic**
</Callout>

---

4. Step-by-Step Instructions

Always use Step inside StepFlow. Each step gets one card.

Rules:

• StepFlow auto-numbers steps: 1, 2, 3, etc.
• Add a description prop for context under the title.
• Include GallerySimple inside steps that need screenshots.
• Use inline Callout (variant="warning" or "tip", with embed) for per-step cautions.

<StepFlow>
  <Step title="Open Patient Search" description="Search using name or IC to find duplicates">
    1. From the **CCMS Home Screen**, click **Patient Search**.
    2. Enter the patient's **name** or **partial IC number**.

    <Callout color="green" title="Search Tip" embed>
      Use wildcard search with <code>%</code> for partial matches.
    </Callout>
  </Step>
</StepFlow>

---

5. Troubleshooting

Use Step collapsible with an icon prop — the icon renders as the left marker.

Each issue follows this pattern:

1. Cause: Brief explanation of why it happens
2. Solution: Numbered steps to resolve

<Step collapsible title="Merge button is greyed out" icon={<ShieldAlert size={16} />}>
  **Cause:** You do not have the required role permissions.

  **Solution:**
  1. Close any active consultations.
  2. Verify your account has **Patient Management → Merge** permission.
</Step>

---

6. Related Resources

Use CardGrid (cols=2) with InfoTile (variant="navigation") cards. Each card links to a related FAQ, wiki page, or support channel.

<Grids cols={2} mobile="equal">
  <InfoTile
    variant="navigation"
    title="How to Register a Newborn"
    description="Register a newborn using the mother's record"
    icon={<UserSearch size={20} />}
    to="/docs/faq-tutorials/registration/howto-register-newborn"
  />
</Grids>

---

7. Author

Always end with the Author component. Do not add a trailing metadata line — pageId, lastUpdated, and version info live in the front matter (single source of truth).

## Author

<Author staffId="dr-fuad" />

---

Import Block (Standard)

Every FAQ should import these components at the top:

import Author from '@site/src/components/Author';
import Badge from '@site/src/components/Badge';
import QuickAnswer from '@site/src/components/QuickAnswer';
import Step from '@site/src/components/Step';
import StepFlow from '@site/src/components/StepFlow';
import InfoTile from '@site/src/components/InfoTile';
import Grids from '@site/src/components/Grids';
import { AlertTriangle, ShieldAlert, UserSearch, Merge, MessageCircleQuestion, ExternalLink } from 'lucide-react';

Only import what you actually use. Remove unused imports before publishing.

---

Front Matter (Standard)

---
title: "Descriptive Title in Title Case"
pageId: "FAQ-XXX"
sidebar_position: "N"
sidebar_label: "Short Label"
category: "Faq category-name"
description: "One-line description for search and SEO"
lastUpdated: "YYYY-MM-DD"
status: "Updated"   # or "New", "Draft"
---

---

Visual Hierarchy Cheat Sheet

Element	When to Use
QuickAnswer	TL;DR, quick highlights (preferred, low noise)
Callout (success)	Completion confirmation, strong emphasis
Callout (info)	Prerequisites, helpful context
Callout (warning)	Cautions, irreversible actions
Callout (danger)	Critical time-sensitive warnings
Callout (tip)	Pro tips, shortcuts, best practices
Step inside StepFlow	Numbered procedural steps
Step collapsible with icon	Troubleshooting issues
GallerySimple	Screenshots, visual references
InfoTile (navigation)	Related resource links
Table	Comparison matrices, reference data

---

What NOT to Do

• Don't use plain --- horizontal rules as section dividers inside the content. Use headings instead.
• Don't write massive walls of text. Break content into steps or bullet points.
• Don't use Docusaurus ::: admonitions. Always use the custom Callout component.
• Don't use emoji strings as InfoTile icons. Use Lucide React icons only.
• Don't create FAQ pages without pageId or sidebar_position.
• Don't use variant="step" or variant="stepTop". Use Step inside StepFlow for sequences and Step collapsible for standalone accordion cards.

---

Reference / Hybrid Shape

Some pages legitimately do not fit a single procedural how-to. Examples:

• Decision guides — comparing two or more methods and helping the reader pick one (e.g. confidentiality protection methods).
• Reference tables — audit report categories, error code dictionaries, role-permission matrices.
• Conceptual explainers — how the audit trail works, what RBA means in practice, what a smartcard session is.
• Hybrid pages — content that blends a short conceptual section with a procedure (e.g. "what this is" + "how to apply it").

For these, the strict 7-section template either forces awkward shapes (alternative procedures pretending to be sequential steps) or leaves no room for the comparison or reference content the page is actually about.

Required elements

Even in a reference / hybrid page, keep the page-anchor elements consistent so users still get a predictable experience:

#	Element	Notes
1	TL;DR (QuickAnswer)	Always lead with this — same as the standard shape
2	Problem Statement (second QuickAnswer with title="What Problem Does This Solve?")	Same intentional pattern as the standard
3	Body	Free-form: tables, comparison grids, mini-StepFlows, conceptual paragraphs, embedded Callouts. Use ## headings to chunk it.
4	Troubleshooting (optional)	If the page warrants it, use the same Step collapsible pattern. Skip if not applicable.
5	Related Resources	Same CardGrid + InfoTile pattern
6	Author	Same component

Allowed in the body section

• Multiple ## sub-sections (one per method, concept, or reference cluster)
• Comparison tables at top level (not buried inside a Step)
• Mini-StepFlow blocks inside a ## section, when one of the methods has its own short procedure
• Free-form prose paragraphs, where the value is conceptual rather than action-oriented
• Tabs from @theme/Tabs if the content benefits from a tabbed selector

Frontmatter

Same requirements as the standard shape (title, pageId, sidebar_position, sidebar_label, category, description, lastUpdated, status).

When in doubt

If you're not sure which shape fits, default to the standard 7-section how-to. Only switch to the reference / hybrid shape when you can articulate which specific element of the strict template is getting in the way of the content. The point is flexibility for legitimate exceptions, not an escape hatch from structure.