# Expensify HelpDot Authoring Spec ## Purpose This document defines mandatory structural, formatting, tone, terminology, and retrieval optimization rules for generating Expensify HelpDot articles. All generated articles must comply. --- # 1. Core Principles Every article must: - Solve one primary workflow only - Match real user search intent - Use exact UI terminology - Follow the naming, navigation, and capitalization rules in docs/HELPSITE_NAMING_CONVENTIONS.md - Follow strict heading rules - Be optimized for semantic retrieval - Be concise and actionable If multiple workflows are detected → split into multiple articles. --- # 2. Heading Rules (Strict) ## Forbidden - Generic headings: - Overview - Introduction - Notes - 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 (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 ## Capitalization - Use title case for the article title (the metadata `title` and the `#` title). - Use sentence case for every `##` heading. - Capitalize proper nouns, product names, plan names, and acronyms. Write `# FAQ` in all caps. - Lowercase roles and generic terms (for example, workspace admin, workspace, expense report) unless quoting a UI label. Full capitalization rules are in docs/HELPSITE_NAMING_CONVENTIONS.md. **Valid Examples** # 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` --- # 3. Metadata Requirements (Mandatory) Every article must begin with: ```yaml --- title: Clear Task-Based Title Using Feature Name (title case) description: 1–2 sentence summary of outcome keywords: [primary task phrase, feature name, relevant roles] internalScope: Audience is [target role(s), covers [included workflow], does not cover [explicit exclusions] --- ``` Metadata must reflect real search queries. --- # 4. Required Structural Elements Each article must include: - YAML metadata - 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 --- # 5. Step Formatting Standard Step instructions must be: - Sequential - Clear - Action-oriented - Aligned with actual UI flow Step instructions must also follow docs/HELPSITE_NAMING_CONVENTIONS.md: - Use **select** for interacting with UI elements and **choose** only for decisions between options. Do not use click, tap, hit, press, or push. - Start navigation in the navigation tabs and use a bolded navigation path, such as **Workspaces > [workspace name] > Members**. - Combine web and mobile instructions when navigation is the same. Use separate "On web:" and "On mobile:" instructions when it differs. --- # 6. AI Retrieval Optimization Rules Every article must: - Include at least one full "How to..." heading using feature name - Include realistic search phrases - Avoid vague wording - Avoid multi-feature coverage - Use UI-exact labels - Avoid internal language Do not combine: - Setup + troubleshooting + workspace design - Admin + Member flows unless inseparable --- # 7. Cross-Linking Standards Cross-linking must reinforce the primary workflow, not expand scope or dilute retrieval precision. Links should clarify dependencies or provide deeper context — not function as navigation hubs. --- ## When to Cross-Link Only link in these cases: - Prerequisite workflows required to complete the primary task - Deep-dive explanations that expand on a concept mentioned briefly - Explicitly excluded workflows listed in `internalScope` Avoid linking to tangential, loosely related, or adjacent features. If a workflow is important enough to link repeatedly, it likely requires its own dedicated article. --- ## Anchor Text Rules Anchor text must describe the task or feature clearly. Avoid vague anchors such as: - Click here - Read more - This article Use descriptive formats such as: - Learn how to [complete task] - Learn how to enable [Feature Name] - Learn more about [Feature Name] Anchor text should reflect real search phrasing. --- ## Link Formatting - Use relative links only. - Do not use full URLs. - Do not place links inside numbered step instructions. - Do not interrupt procedural flow with inline links. Place links: - After explanatory sentences - In conditional dependency statements - In explanatory paragraphs (not within step actions) --- ## Link Volume Limit cross-links to preserve topical clarity. Excessive linking: - Dilutes the primary workflow - Introduces unrelated entities - Reduces retrieval precision If multiple related workflows must be referenced, consider consolidating them into a dedicated supporting article instead of embedding many links. --- ## Related Articles Section (Optional) A "Related articles" section may be used only when: - Multiple prerequisite or deep-dive workflows are necessary - Inline linking would clutter the main content If used: - Place it at the end of the article - Use a `## Related articles` heading - Limit to essential supporting workflows only Do not use this section as a directory or feature hub. --- # 8. Screenshot Guidelines Only suggest screenshots when they meaningfully improve a member's understanding of the article. Screenshots are optional—not every article or workflow requires them. ## Screenshot Decision Criteria Suggest a screenshot only if it accomplishes one or more of the following: * Helps members orient themselves within an interface by confirming they are on the correct page or screen * Clarifies a complex or highly visual workflow * Highlights an important setting, filter, configuration option, decision point, or UI element * Demonstrates a feature or capability that is easier to understand visually * Shows a confirmation state or error message that members should recognize * Shows a critical step that cannot be adequately described through text alone, particularly when members must locate a specific page, setting, or control * Addresses an area that is likely to generate member confusion or support questions * Guides members through a workflow in a connected third-party platform, where a screenshot can help them locate the correct page, setting, or control. The interface may be Expensify or a connected third-party platform. Do **not** suggest a screenshot if it would: * Replace written instructions instead of supporting them * Document every step of a workflow * Simply mirror or duplicate the surrounding text * Show a simple, obvious interface that members can easily identify from the instructions alone * Add maintenance overhead without significantly improving comprehension Before suggesting a screenshot, ask: > **What specific confusion would this screenshot prevent or resolve?** If there is no clear answer, do not suggest a screenshot. ## Screenshot Placeholder Format (Non-Rendered) Screenshot suggestions must use HTML comments so they remain invisible in the rendered HelpDot article. Use this exact structure: ```html ``` Rules: * Must begin with `` * Must not appear inline within a sentence * Place immediately after the section or step it supports * Describe the exact UI state to capture rather than the general page * The **Purpose** must explain the unique value of the screenshot. Do not use generic statements such as "Provides a visual reference." --- # 9. Pre-Publish Validation Checklist 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 - Article title uses title case; every ## heading uses sentence case - UI references follow docs/HELPSITE_NAMING_CONVENTIONS.md, including: - **select** (or **choose** for decisions) instead of click or tap - Navigation tabs, bolded navigation paths with lowercase placeholders, and the navigation menu - **More (⋮)** for the three dots menu - **field** for text-entry controls and "selection bar" for the bulk actions menu - "Enable" or "disable" for toggles - Color used only as a secondary descriptor - Lowercase roles and generic terms; capitalized plan names with lowercase "plan" - "This feature is only available on web/mobile" for platform limitations - Metadata aligns with search intent - Navigation included (if applicable) - Single workflow only - Includes at least one "How to" heading - Cross-links follow Cross-Linking Standards - Every suggested screenshot has a clear purpose that prevents or resolves a specific member confusion If any condition fails → regenerate.