From 791337fb09159e9da6b6e62d256087bd7804dec9 Mon Sep 17 00:00:00 2001 From: "Stephanie Elliott (via MelvinBot)" Date: Fri, 13 Mar 2026 20:48:55 +0000 Subject: [PATCH 1/2] Strengthen help site governance rules for heading structure and task-based requirements Clarifies ambiguous heading rules to prevent multiple # headings and non-task-based section titles in HelpDot articles. Co-authored-by: Stephanie Elliott --- docs/HELPSITE_NAMING_CONVENTIONS.md | 2 ++ docs/HELP_AUTHORING_GUIDELINES.md | 29 ++++++++++++++++++++++++----- 2 files changed, 26 insertions(+), 5 deletions(-) diff --git a/docs/HELPSITE_NAMING_CONVENTIONS.md b/docs/HELPSITE_NAMING_CONVENTIONS.md index 270f9d64aa3d7..e9a7e9e2c4c30 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. 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..7302fcb8b5f08 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 + - 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,11 @@ 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) + - 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) From 3c10b574f43bc33c0e6ef8576a645bd92d3084ba Mon Sep 17 00:00:00 2001 From: "Stephanie Elliott (via MelvinBot)" Date: Tue, 17 Mar 2026 00:58:18 +0000 Subject: [PATCH 2/2] Exempt # FAQ from task-based heading requirement All articles should have a # FAQ section, so it needs to be explicitly exempted from the rule requiring headings to start with an action verb or question word. Co-authored-by: Stephanie Elliott --- docs/HELPSITE_NAMING_CONVENTIONS.md | 2 +- docs/HELP_AUTHORING_GUIDELINES.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/HELPSITE_NAMING_CONVENTIONS.md b/docs/HELPSITE_NAMING_CONVENTIONS.md index e9a7e9e2c4c30..356f7965df2fa 100644 --- a/docs/HELPSITE_NAMING_CONVENTIONS.md +++ b/docs/HELPSITE_NAMING_CONVENTIONS.md @@ -10,7 +10,7 @@ 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. This includes section headings that reference UI features — they must still be task-based, not just feature labels. +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. --- diff --git a/docs/HELP_AUTHORING_GUIDELINES.md b/docs/HELP_AUTHORING_GUIDELINES.md index 7302fcb8b5f08..a282f60e28953 100644 --- a/docs/HELP_AUTHORING_GUIDELINES.md +++ b/docs/HELP_AUTHORING_GUIDELINES.md @@ -40,7 +40,7 @@ If multiple workflows are detected → split into multiple articles. ## Requirements -- All headings must be: +- 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 @@ -243,6 +243,7 @@ Before outputting an article, confirm: - 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