diff --git a/docs/HELPSITE_NAMING_CONVENTIONS.md b/docs/HELPSITE_NAMING_CONVENTIONS.md index 270f9d64aa3d7..356f7965df2fa 100644 --- a/docs/HELPSITE_NAMING_CONVENTIONS.md +++ b/docs/HELPSITE_NAMING_CONVENTIONS.md @@ -10,6 +10,8 @@ This document governs UI language conventions. It does not define article struct docs/HELP_AUTHORING_GUIDELINES.md +Note: All article headings (# and ##) must follow the task-based heading rules in HELP_AUTHORING_GUIDELINES.md Section 2, except for `# FAQ` which is exempt. This includes section headings that reference UI features — they must still be task-based, not just feature labels. + --- # Core UI Referencing Rules diff --git a/docs/HELP_AUTHORING_GUIDELINES.md b/docs/HELP_AUTHORING_GUIDELINES.md index 1907b04f1a40d..a282f60e28953 100644 --- a/docs/HELP_AUTHORING_GUIDELINES.md +++ b/docs/HELP_AUTHORING_GUIDELINES.md @@ -34,11 +34,14 @@ If multiple workflows are detected → split into multiple articles. - Setup - Options - Step 1 +- Noun-only or topic-only headings that describe a category rather than a task +- Platform-only labels used as headings (e.g., "iPhone", "Android", "Desktop", "Web") +- Any heading that does not describe an action the user takes or a question the user has ## Requirements -- All headings must be: - - Task-based +- All headings must be (except `# FAQ`, which is exempt from task-based rules): + - Task-based — must describe what the user will do or learn. Start with an action verb or question word (How, What, Where, Who, Why, When) - Searchable - Explicit - Feature-specific @@ -48,6 +51,15 @@ If multiple workflows are detected → split into multiple articles. # Who can connect a business bank account in Expensify ## Where to enable ACH reimbursements in a Workspace ## How to troubleshoot bank connection errors in Expensify +## How to enable Expensify Card notifications on iPhone + +**Invalid → Corrected Examples** + +- ❌ `## Transaction decline notifications` → ✅ `## How to understand why your Expensify Card transaction was declined` +- ❌ `## iPhone` → ✅ `## How to enable notifications on iPhone` +- ❌ `## Suspected fraud notifications` → ✅ `## What to do when you receive a fraud alert` +- ❌ `## Banking and settlement notifications` → ✅ `## How banking and settlement alerts work for admins` +- ❌ `## Card lifecycle notifications` → ✅ `## What card lifecycle notifications you'll receive` --- @@ -72,11 +84,15 @@ Metadata must reflect real search queries. Each article must include: - YAML metadata - - One primary # heading - - Task-based ## sections + - Exactly one # heading (the article title). No other # headings are allowed except # FAQ + - Task-based ## sections for all content below the title - Sequential numbered steps (if procedural) - An FAQ section (if needed) +Do not use multiple # headings to organize an article into major sections. If content feels like it needs its own # heading, either: + - Demote it to ## under the single # title, or + - Split it into a separate article (per Section 1: one workflow per article) + If including an FAQ section, it must comply with: /docs/HELPSITE_NAMING_CONVENTIONS.md @@ -224,8 +240,12 @@ Prioritize screenshots for: # 9. Pre-Publish Validation Checklist Before outputting an article, confirm: - - Only # and ## used - - No generic headings + - Exactly one # heading (the article title), plus optional # FAQ — no other # headings + - Only ## used for all content sections (no ### or deeper) + - Every ## heading starts with an action verb or question word (How, What, Where, Who, Why, When) + - `# FAQ` is exempt from task-based heading rules + - No noun-only, topic-only, or platform-only headings + - No generic headings (Overview, Introduction, Notes, Setup, Options, Step 1) - Feature names match UI - Metadata aligns with search intent - Navigation included (if applicable)