[NO QA] Strengthen help site governance rules for headings

[MelvinBot]

Explanation of Change

Strengthens the HelpDot governance rules in HELP_AUTHORING_GUIDELINES.md and HELPSITE_NAMING_CONVENTIONS.md to prevent two categories of article violations that were occurring:

1. Multiple # headings: The phrase "One primary # heading" was ambiguous — "primary" could be read as allowing additional # headings. Replaced with "Exactly one # heading (the article title). No other # headings are allowed except # FAQ" and added explicit guidance on what to do when content seems to need its own # heading.

2. Non-task-based headings: The forbidden heading list only covered 6 generic words and "task-based" was undefined. Expanded the forbidden list to include noun-only, topic-only, and platform-only headings. Added a definition of "task-based" (must start with action verb or question word) and added invalid-to-corrected examples.

3. Pre-publish checklist gaps: The checklist only checked heading depth, not count or task-based compliance. Updated to check for exactly one # heading, task-based ## headings, and no noun/topic/platform-only headings.

4. Cross-reference in naming conventions: Added a note in HELPSITE_NAMING_CONVENTIONS.md reinforcing that headings referencing UI features must still follow the task-based heading rules.

These changes were proposed in this analysis.

Fixed Issues

$ https://github.com/Expensify/Expensify/issues/606988

Tests

1. Review the diff to confirm each change matches the proposed corrections from the issue analysis
2. Verify HELP_AUTHORING_GUIDELINES.md Section 4 now says "Exactly one # heading" instead of "One primary # heading"
3. Verify Section 2 Forbidden list now includes noun-only, topic-only, and platform-only headings
4. Verify Section 2 Requirements now defines "Task-based" with action verb/question word requirement
5. Verify Section 2 now includes Invalid → Corrected Examples
6. Verify Section 9 Pre-Publish Checklist now checks heading count, task-based compliance, and forbidden heading types
7. Verify HELPSITE_NAMING_CONVENTIONS.md now includes cross-reference note about task-based heading rules

• Verify that no errors appear in the JS console

Offline tests

N/A — documentation-only changes.

QA Steps

[No QA] — these are documentation governance files only, no application code changes.

• Verify that no errors appear in the JS console

PR Author Checklist

• I linked the correct issue in the ### Fixed Issues section above
• I wrote clear testing steps that cover the changes made in this PR
  • I added steps for local testing in the Tests section
  • I added steps for the expected offline behavior in the Offline steps section
  • I added steps for Staging and/or Production testing in the QA steps section
  • I added steps to cover failure scenarios (i.e. verify an input displays the correct error message if the entered data is not correct)
  • I turned off my network connection and tested it while offline to ensure it matches the expected behavior (i.e. verify the default avatar icon is displayed if app is offline)
  • I tested this PR with a High Traffic account against the staging or production API to ensure there are no regressions (e.g. long loading states that impact usability).
• I included screenshots or videos for tests on all platforms
• I ran the tests on all platforms & verified they passed on:
  • Android: Native
  • Android: mWeb Chrome
  • iOS: Native
  • iOS: mWeb Safari
  • MacOS: Chrome / Safari
• I verified there are no console errors (if there's a console error not related to the PR, report it or open an issue for it to be fixed)
• I followed proper code patterns (see Reviewing the code)
  • I verified that any callback methods that were added or modified are named for what the method does and never what callback they handle (i.e. toggleReport and not onIconClick)
  • I verified that comments were added to code that is not self explanatory
  • I verified that any new or modified comments were clear, correct English, and explained "why" the code was doing something instead of only explaining "what" the code was doing.
  • I verified any copy / text shown in the product is localized by adding it to src/languages/* files and using the translation method
    • If any non-english text was added/modified, I used JaimeGPT to get English > Spanish translation. I then posted it in #expensify-open-source and it was approved by an internal Expensify engineer. Link to Slack message:
  • I verified all numbers, amounts, dates and phone numbers shown in the product are using the localization methods
  • I verified any copy / text that was added to the app is grammatically correct in English. It adheres to proper capitalization guidelines (note: only the first word of header/labels should be capitalized), and is either coming verbatim from figma or has been approved by marketing (in order to get marketing approval, ask the Bug Zero team member to add the Waiting for copy label to the issue)
  • I verified proper file naming conventions were followed for any new files or renamed files. All non-platform specific files are named after what they export and are not named "index.js". All platform-specific files are named for the platform the code supports as outlined in the README.
  • I verified the JSDocs style guidelines (in STYLE.md) were followed
• If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
• I followed the guidelines as stated in the Review Guidelines
• I tested other components that can be impacted by my changes (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar are working as expected)
• I verified all code is DRY (the PR doesn't include any logic written more than once, with the exception of tests)
• I verified any variables that can be defined as constants (ie. in CONST.ts or at the top of the file that uses the constant) are defined as such
• I verified that if a function's arguments changed that all usages have also been updated correctly
• If any new file was added I verified that:
  • The file has a description of what it does and/or why is needed at the top of the file if the code is not self explanatory
• If a new CSS style is added I verified that:
  • A similar style doesn't already exist
  • The style can't be created with an existing StyleUtils function (i.e. StyleUtils.getBackgroundAndBorderStyle(theme.componentBG))
• If new assets were added or existing ones were modified, I verified that:
  • The assets are optimized and compressed (for SVG files, run npm run compress-svg)
  • The assets load correctly across all supported platforms.
• If the PR modifies code that runs when editing or sending messages, I tested and verified there is no unexpected behavior for all supported markdown - URLs, single line code, code blocks, quotes, headings, bold, strikethrough, and italic.
• If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected in all cases)
• If the PR modifies a component related to any of the existing Storybook stories, I tested and verified all stories for that component are still working as expected.
• If the PR modifies a component or page that can be accessed by a direct deeplink, I verified that the code functions as expected when the deeplink is used - from a logged in and logged out account.
• If the PR modifies the UI (e.g. new buttons, new UI components, changing the padding/spacing/sizing, moving components, etc) or modifies the form input styles:
  • I verified that all the inputs inside a form are aligned with each other.
  • I added Design label and/or tagged @Expensify/design so the design team can review the changes.
• If a new page is added, I verified it's using the ScrollView component to make it scrollable when more elements are added to the page.
• I added unit tests for any new feature or bug fix in this PR to help automatically prevent regressions in this user flow.
• If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.

Screenshots/Videos

Android: Native

N/A — documentation-only changes

Android: mWeb Chrome

N/A — documentation-only changes

iOS: Native

N/A — documentation-only changes

iOS: mWeb Safari

N/A — documentation-only changes

MacOS: Chrome / Safari

N/A — documentation-only changes

[OSBotify]

A preview of your ExpensifyHelp changes have been deployed to https://a75b2478.helpdot.pages.dev ⚡️

Updated articles:

• HELP_AUTHORING_GUIDELINES
• HELPSITE_NAMING_CONVENTIONS

[melvin-bot]

@QichenZhu Please copy/paste the Reviewer Checklist from here into a new comment on this PR and complete it. If you have the K2 extension, you can simply click: [this button]

[melvin-bot]

@bernhardoj Please copy/paste the Reviewer Checklist from here into a new comment on this PR and complete it. If you have the K2 extension, you can simply click: [this button]

[github-actions]

HelpDot Documentation Review

Overall Assessment

This PR tightens the HelpDot governance rules around heading structure and task-based heading requirements. The changes are well-motivated -- replacing ambiguous "one primary # heading" language with "Exactly one # heading" and expanding the forbidden headings list to explicitly ban noun-only, topic-only, and platform-only headings. The additions are clear, actionable, and directly address real drift scenarios (e.g., using "iPhone" or "Transaction decline notifications" as headings). The before/after examples are particularly strong and will help authors self-correct.

Scores Summary

• Readability: 9/10 - The new rules are written in clear, imperative language with good scannability. The "Invalid to Corrected Examples" block is easy to parse. Minor deduction: the Section 4 guidance paragraph ("If content feels like it needs its own # heading, either:") uses slightly softer language ("feels like") than the otherwise deterministic tone of the document.
• AI Readiness: 8/10 - The changes meaningfully improve AI retrieval guidance by defining what "task-based" means (action verb or question word), listing the allowed question words explicitly, and adding the checklist item for verb/question-word starts. Minor deduction: TEMPLATE.md still uses the old "One primary workflow per article" phrasing without the strengthened "Exactly one # heading" rule, which could cause an AI agent to apply inconsistent rules depending on which governance file it retrieves.
• Style Compliance: 8/10 - The changes align well with the existing governance style: imperative rules, explicit correct/incorrect examples, and deterministic phrasing. Two issues reduce the score: (1) the cross-reference note added to HELPSITE_NAMING_CONVENTIONS.md is plain text rather than following the bold/structured formatting pattern used elsewhere in that document, and (2) TEMPLATE.md was not updated to match, creating a cross-document inconsistency.

Key Findings

Strengths

• The "Invalid to Corrected Examples" block in Section 2 is excellent. It provides five concrete before/after pairs covering different heading anti-patterns (noun-only, platform-only, vague topic). This is the most impactful addition in the PR.
• Replacing "One primary # heading" with "Exactly one # heading (the article title). No other # headings are allowed except # FAQ" eliminates ambiguity. The old wording ("primary") could be interpreted as allowing secondary # headings.
• The expanded forbidden list is well-structured: it progresses from specific patterns (noun-only, platform-only) to a catch-all rule ("Any heading that does not describe an action the user takes or a question the user has").
• The Pre-Publish Validation Checklist updates in Section 9 mirror the new rules precisely, ensuring authors have a concrete gate to check against.

Issues to Address

1. Cross-document inconsistency with TEMPLATE.md: The template file still contains the HTML comment "One primary workflow per article" and uses # [This must match the article title exactly] plus # FAQ but does not reference the new "Exactly one #" rule. Since TEMPLATE.md is the file authors copy when creating new articles, it should reflect the strengthened language. Consider adding a comment such as: <!-- Exactly one # heading allowed. No other # headings except # FAQ. See HELP_AUTHORING_GUIDELINES.md Section 4. -->

2. Self-consistency within HELP_AUTHORING_GUIDELINES.md: The governance document itself uses multiple # headings for its numbered sections (# 1. Core Principles, # 2. Heading Rules, etc.) and its ## headings are not task-based (## Forbidden, ## Requirements, ## Purpose, ## Anchor Text Rules, etc.). The new rules state "Exactly one # heading" and "Every ## heading starts with an action verb or question word." While these rules clearly apply to HelpDot articles rather than the governance doc itself, this distinction is never stated explicitly. An author or AI agent reading the governance doc could be confused by the apparent contradiction. A brief scoping note -- such as "These rules apply to published HelpDot articles, not to governance documents themselves" -- would resolve this.

3. "# FAQ" exception could be more prominent: Section 4 mentions the # FAQ exception in the bullet point, but the new guidance paragraph immediately below ("Do not use multiple # headings to organize an article into major sections") does not reiterate the FAQ exception. An author reading that paragraph in isolation might think # FAQ is also prohibited. Consider appending "(# FAQ is the sole exception)" to that paragraph.

4. Formatting of the cross-reference note in HELPSITE_NAMING_CONVENTIONS.md: The added note sits as a plain-text paragraph between the docs/HELP_AUTHORING_GUIDELINES.md reference and the --- separator. It could benefit from being formatted as an explicit callout or placed under a small sub-heading to match the structured style of the rest of the document. At minimum, bolding "Note:" would improve scannability.

5. Question-word list completeness: The new rule specifies six allowed question words: "How, What, Where, Who, Why, When." This is a good explicit list, but it may not cover all valid task-based heading patterns. For example, "Can members override workspace-level settings?" starts with "Can" (not in the list). The existing TEMPLATE.md FAQ section uses headings starting with "Can," "Why," and "Does" -- "Does" is also not in the approved list. Consider either expanding the list to include "Can," "Does," and "Do," or clarifying that FAQ headings may use additional question words.

Recommendations

1. Update TEMPLATE.md to reflect the "Exactly one # heading" rule and the task-based heading requirement. This is the highest-priority gap, since the template is what authors directly copy.

2. Add a scoping statement early in HELP_AUTHORING_GUIDELINES.md (e.g., in the Purpose section or Section 2 preamble) clarifying that the heading rules apply to published HelpDot articles, not to the governance documents themselves.

3. Expand the allowed question-word list to include "Can," "Do," and "Does," or add a note that FAQ question headings may use any natural question form. This prevents the rules from inadvertently prohibiting valid FAQ headings already present in the template.

4. Reiterate the # FAQ exception in the new Section 4 guidance paragraph to avoid ambiguity when read in isolation.

5. Format the cross-reference note in HELPSITE_NAMING_CONVENTIONS.md with bold emphasis on "Note:" for consistency with the document's structured style.

Files Reviewed

• docs/HELPSITE_NAMING_CONVENTIONS.md (+2 lines): Cross-reference note added. Functional and accurate, but could benefit from formatting improvements and slightly more prominent placement.
• docs/HELP_AUTHORING_GUIDELINES.md (+24/-5 lines): Substantial and well-targeted improvements to Sections 2, 4, and 9. The expanded forbidden list, task-based definition, corrected examples, and checklist updates are all strong additions. Cross-document consistency with TEMPLATE.md and self-consistency within the doc are the main gaps.

This review assessed only the proposed changes in the diff, not unchanged portions of the files.

[github-actions]

test connection

[github-actions]

Inline Review: Governance Rule Updates

I reviewed the diff for PR #85271. Below are the findings organized by file and line number. Since inline comment creation requires additional permissions, I am posting all findings as a single PR comment with file/line references.

---

docs/HELP_AUTHORING_GUIDELINES.md

Line 44 -- Internal consistency gap (question word list vs. TEMPLATE.md)

The new requirement says headings must "Start with an action verb or question word (How, What, Where, Who, Why, When)." However, the official TEMPLATE.md uses FAQ headings that begin with words NOT on this list:

• ## Can members [Common Task Variation Using Feature Name]?
• ## Does [Feature Name] work with [Integration or Related Feature]?

Under the new rule as written, these template-sanctioned FAQ headings would be flagged as violations. Consider either:
(a) expanding the allowed list to include common question starters used in FAQ sections (Can, Does, Do, Is, Are), or
(b) adding an explicit exemption stating that ## headings inside the # FAQ section may use additional question starters.

---

Line 245 -- Same consistency gap in Pre-Publish Validation Checklist

The checklist item "Every ## heading starts with an action verb or question word (How, What, Where, Who, Why, When)" mirrors the Section 2 rule and inherits the same conflict with TEMPLATE.md FAQ headings. This should be updated to match whatever resolution is chosen for line 44.

---

Line 59 -- Missing feature name in corrected example

The corrected heading ## How to enable notifications on iPhone does not include an Expensify feature name. Section 2 requires headings to be "Feature-specific," and Section 6 requires at least one "How to..." heading using the feature name. Consider: ## How to enable Expensify Card notifications on iPhone (which is already used as a valid example on line 54, making this corrected version weaker than the example directly above it).

---

Line 60 -- Missing feature name in corrected example

## What to do when you receive a fraud alert does not mention a specific Expensify feature. Per the "Feature-specific" requirement in Section 2 and Section 6 feature-name requirement, consider: ## What to do when you receive an Expensify Card fraud alert.

---

Line 61 -- Missing feature name in corrected example

## How banking and settlement alerts work for admins is generic -- it does not reference a specific Expensify feature. Consider: ## How Expensify Card banking and settlement alerts work for admins to satisfy the "Feature-specific" heading requirement in Section 2.

---

docs/HELPSITE_NAMING_CONVENTIONS.md

Line 12 -- Scope tension with Purpose section

Lines 9-11 of this file state: "This document governs UI language conventions. It does not define article structure or Markdown formatting rules." However, the new note on line 12 introduces an article-structure rule (task-based heading requirements) into a document that explicitly disclaims structural guidance.

Consider either:
(a) moving this cross-reference into HELP_AUTHORING_GUIDELINES.md as a note in Section 2, or
(b) softening the wording to a pure cross-reference without restating the rule, e.g.: "For heading rules that apply to all # and ## headings, see HELP_AUTHORING_GUIDELINES.md Section 2."

---

Summary

#	File	Line	Category	Severity
1	HELP_AUTHORING_GUIDELINES.md	44	Internal consistency	High -- contradicts TEMPLATE.md
2	HELP_AUTHORING_GUIDELINES.md	245	Internal consistency	High -- same issue as #1
3	HELP_AUTHORING_GUIDELINES.md	59	Example quality	Medium -- violates own Feature-specific rule
4	HELP_AUTHORING_GUIDELINES.md	60	Example quality	Medium -- violates own Feature-specific rule
5	HELP_AUTHORING_GUIDELINES.md	61	Example quality	Medium -- violates own Feature-specific rule
6	HELPSITE_NAMING_CONVENTIONS.md	12	Cross-reference accuracy	Medium -- contradicts Purpose scope

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 791337fb09

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[QichenZhu]

I don't think this needs a C+ review, so just approving this to unblock the process.

[melvin-bot]

🎯 @QichenZhu, thanks for reviewing and testing this PR! 🎉

An E/App issue has been created to issue payment here: #85339.

[melvin-bot]

@Ollyws Please copy/paste the Reviewer Checklist from here into a new comment on this PR and complete it. If you have the K2 extension, you can simply click: [this button]

[OSBotify]

🚀 Deployed to staging by https://github.com/VictoriaExpensify in version: 9.3.40-0 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	failure ❌
🍎 iOS 🍎	success ✅

[OSBotify]

🚀 Deployed to staging by https://github.com/VictoriaExpensify in version: 9.3.40-0 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅