[WIP - hold] Update authoring guidance files for the help site by stephanieelliott · Pull Request #95314 · Expensify/App

stephanieelliott · 2026-07-04T03:58:09Z

Added Task and Topic files for different article types
Added screenshot guidance to all authoring files

Related: https://github.com/Expensify/Expensify/issues/635904

Refactor authoring guidelines to use bullet points for clarity and consistency.

This template provides a structure for writing topic articles, including guidelines for titles, introductions, and section headings.

melvin-bot · 2026-07-04T03:58:37Z

@Gonals 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]

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d1178576d6

ℹ️ 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".

chatgpt-codex-connector · 2026-07-04T04:00:58Z

@@ -0,0 +1,138 @@
+---


Exclude the new templates from the Help site build

Because this new root-level Markdown file has YAML front matter, Jekyll treats it as an HTML page; docs/_config.yml only excludes TEMPLATE.md, and docs/sitemap.xml emits every site.html_pages entry unless sitemap: false is set. After deployment, /TEMPLATE-task (and the same pattern in TEMPLATE-topic.md) can be published and indexed as a customer-facing Help page instead of remaining an authoring-only template. Please add these files to the exclude list or mark them non-indexed/non-published.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-07-04T04:00:58Z

+---
+title: Clear task-based title using the feature name
+description: A concise summary of the article for search results.
+keywords: [primary search phrases]
+internalScope: Audience is [who this article is for]. Covers [single workflow]. Does not cover [closely related workflows].
+---


Add required task metadata to the template

The new task guidelines say every task article must include contentType: task and platform, and the topic template already includes its equivalents, but this task template omits both fields. Authors copying this template will produce task articles that immediately fail the metadata checklist in HELP_AUTHORING_GUIDELINES_TASK.md and won't carry the intended content-type/platform classification.

Useful? React with 👍 / 👎.

github-actions · 2026-07-04T04:01:50Z

+title: Clear task-based title using the feature name
+description: A concise summary of the article for search results.
+keywords: [primary search phrases]
+internalScope: Audience is [who this article is for]. Covers [single workflow]. Does not cover [closely related workflows].


Missing required metadata: The Task article guidance added in this PR (HELP_AUTHORING_GUIDELINES_TASK.md Section 4) requires every task article to include contentType: task and platform: [platform value] in the YAML frontmatter. This template omits both fields, while TEMPLATE-topic.md includes them. Add these two fields so authors copying this template produce compliant metadata:

Suggested change

internalScope: Audience is [who this article is for]. Covers [single workflow]. Does not cover [closely related workflows].

internalScope: Audience is [who this article is for]. Covers [single workflow]. Does not cover [closely related workflows].

contentType: task

platform: [platform value]

github-actions · 2026-07-04T04:01:52Z

+
+-->
+
+## Related Articles


Heading casing inconsistency: The governance-specified heading is ## Related articles (sentence case), per HELP_AUTHORING_GUIDELINES.md Section 7 and TEMPLATE-topic.md (line 119). This uses title case ("Related Articles"). Use sentence case for consistency across templates.

Suggested change

## Related Articles

## Related articles

github-actions · 2026-07-04T04:01:56Z

+
+If they're identical, combine them.
+
+<!-- SCREENSHOT:


Screenshot placeholder does not match required format: The updated screenshot standard in this PR (HELP_AUTHORING_GUIDELINES.md lines 60-62 and 85) requires each field to carry descriptive guidance, and the Purpose must state "what specific confusion this screenshot prevents or resolves" (not a generic value). This template's block leaves Suggestion:, Location:, and Purpose: blank with no bracketed prompts, so it does not model the mandated structure. Align it with the standard:

Suggested change

<!-- SCREENSHOT:

github-actions · 2026-07-04T04:02:00Z

+
+Titles may:
+
+- Be a concise noun phrase.


Conflicts with task-based heading rule: HELPSITE_NAMING_CONVENTIONS.md (line 13) and HELP_AUTHORING_GUIDELINES.md Section 2 require all headings — including the # article title — to be task-based (start with How/What/Where/Who/Why/When) and explicitly forbid "noun-only or topic-only headings" (except # FAQ). Recommending a "concise noun phrase" title, with examples like "Billing issues", "Annual subscriptions", and "Workspace roles" (lines 54-57), directly contradicts that rule. Either reconcile the base spec with this topic guidance or change these examples/guidance to task-based/question-based titles (e.g. "How billing works", "How annual subscriptions work").

github-actions · 2026-07-04T04:02:53Z

HelpDot Documentation Review

Overall Assessment

This PR updates the HelpDot governance and template files themselves (not help articles). It refines the screenshot guidance in the master authoring spec and adds four new files: dedicated Task and Topic authoring guidelines (HELP_AUTHORING_GUIDELINES_TASK.md, HELP_AUTHORING_GUIDELINES_TOPIC.md) and matching templates (TEMPLATE-task.md, TEMPLATE-topic.md). The changes are well-structured, purposeful, and materially raise the bar on screenshot discipline by requiring each screenshot to justify the specific confusion it resolves. Because these files define the standards, they were assessed for clarity, internal consistency, and alignment with the existing governance in HELP_AUTHORING_GUIDELINES.md, HELPSITE_NAMING_CONVENTIONS.md, and TEMPLATE.md.

Scores Summary

Readability: 9/10 - Clean, scannable structure with consistent bullet lists, clear "Do / Do not" framing, and a strong recurring "What specific confusion would this screenshot prevent or resolve?" prompt. Very easy to follow.
AI Readiness: 7/10 - The new guideline files correctly formalize internalScope, contentType, and platform metadata, and enforce task-based headings. Points deducted for template/metadata inconsistencies (see findings) that would propagate into generated articles.
Style Compliance: 8/10 - Strong adherence to naming conventions and terminology guidance. Minor internal inconsistencies with the master spec's heading-hierarchy rule and mixed use of "customer" vs "member" across files.

Key Findings

Positives

The upgraded screenshot guidance (decision criteria, the mandatory purpose prompt, and the validation-checklist addition) is a clear, high-value improvement applied consistently across all four new/updated files.
Splitting guidance into Task vs Topic article types is a sensible structural improvement, and both files close with a "reads like an experienced Expensify support agent" quality bar.
Metadata blocks now consistently document internalScope, which directly supports AI retrieval.

Issues to address

Template metadata inconsistency (highest priority): TEMPLATE-task.md frontmatter omits contentType and platform, but its own guideline file (HELP_AUTHORING_GUIDELINES_TASK.md, Section 4) requires both, and TEMPLATE-topic.md includes them. Add contentType: task and platform: [platform] to TEMPLATE-task.md.
Screenshot placeholder inconsistency: The new templates and guidelines standardize the non-rendered SCREENSHOT HTML-comment format, but the legacy docs/TEMPLATE.md (not touched by this PR) still uses the rendered "ADD A SCREENSHOT HERE." block. This now conflicts with the guidance this PR establishes.
Terminology drift: The updated master spec and templates use "member," while the new Task/Topic guideline files predominantly use "customer." HELPSITE_NAMING_CONVENTIONS.md treats "Member" as product terminology; align on one audience term for consistency.
Heading-hierarchy note: The new Task/Topic guideline files use multiple top-level headings for their own sections. That is acceptable for a spec document, but worth a brief note clarifying these are governance docs, not articles, so they aren't mistaken as violating the "one H1 per article" rule.

Recommendations

Add contentType and platform to TEMPLATE-task.md frontmatter to match its guideline file and TEMPLATE-topic.md.
Update docs/TEMPLATE.md to use the non-rendered SCREENSHOT HTML-comment format so it matches the standard this PR establishes (or note that it is superseded by the new templates).
Standardize audience terminology ("member" vs "customer") across all authoring files.
Optional: cross-reference the new Task/Topic files from the master HELP_AUTHORING_GUIDELINES.md so authors know when to use each.

Files Reviewed

docs/HELP_AUTHORING_GUIDELINES.md - Improved screenshot section and validation checklist. Strong.
docs/HELP_AUTHORING_GUIDELINES_TASK.md - New, well-structured task guidance. Solid.
docs/HELP_AUTHORING_GUIDELINES_TOPIC.md - New, well-structured topic guidance. Solid.
docs/TEMPLATE-task.md - New template; missing contentType/platform frontmatter.
docs/TEMPLATE-topic.md - New template; complete frontmatter, good inline guidance.

Note: This PR modifies governance/template files rather than help articles, so feedback focuses on internal consistency and alignment with existing standards.

OSBotify · 2026-07-04T04:14:33Z

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

Updated articles:

stephanieelliott added 5 commits July 3, 2026 17:51

Update HELP_AUTHORING_GUIDELINES.md

8158040

Create HELP_AUTHORING_GUIDELINES_TASK.md

9dc87e4

Update HELP_AUTHORING_GUIDELINES_TOPIC.md formatting

2a39030

Refactor authoring guidelines to use bullet points for clarity and consistency.

Create TEMPLATE-task.md

605fe9b

Add template for topic articles in documentation

d117857

This template provides a structure for writing topic articles, including guidelines for titles, introductions, and section headings.

stephanieelliott self-assigned this Jul 4, 2026

stephanieelliott requested a review from a team as a code owner July 4, 2026 03:58

melvin-bot Bot requested review from Gonals and removed request for a team July 4, 2026 03:58

This comment has been minimized.

Sign in to view

chatgpt-codex-connector Bot reviewed Jul 4, 2026

View reviewed changes

github-actions Bot reviewed Jul 4, 2026

View reviewed changes

stephanieelliott removed the request for review from Gonals July 4, 2026 04:12

stephanieelliott changed the title ~~Update authoring guidance files for the help site~~ [WIP - hold] Update authoring guidance files for the help site Jul 4, 2026

Update TEMPLATE-task.md

fd97460

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[WIP - hold] Update authoring guidance files for the help site #95314

[WIP - hold] Update authoring guidance files for the help site #95314
stephanieelliott wants to merge 6 commits into
mainfrom
helpsite-update-authorfiles

stephanieelliott commented Jul 4, 2026

Uh oh!

melvin-bot Bot commented Jul 4, 2026

Uh oh!

This comment has been minimized.

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jul 4, 2026

Uh oh!

chatgpt-codex-connector Bot Jul 4, 2026

Uh oh!

github-actions Bot Jul 4, 2026

Uh oh!

github-actions Bot Jul 4, 2026

Uh oh!

github-actions Bot Jul 4, 2026

Uh oh!

github-actions Bot Jul 4, 2026

Uh oh!

github-actions Bot commented Jul 4, 2026

Uh oh!

OSBotify commented Jul 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

stephanieelliott commented Jul 4, 2026

Uh oh!

melvin-bot Bot commented Jul 4, 2026

Uh oh!

This comment has been minimized.

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 4, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jul 4, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 4, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 4, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 4, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 4, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 4, 2026

HelpDot Documentation Review

Overall Assessment

Scores Summary

Key Findings

Recommendations

Files Reviewed

Uh oh!

OSBotify commented Jul 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants