Skip to content

Docs updates for E/A#87928 Unified private personal details form with magic code#90803

Open
MelvinBot wants to merge 1 commit into
mainfrom
docs-updates-for-87928
Open

Docs updates for E/A#87928 Unified private personal details form with magic code#90803
MelvinBot wants to merge 1 commit into
mainfrom
docs-updates-for-87928

Conversation

@MelvinBot
Copy link
Copy Markdown
Contributor

Summary

  • Updates help site articles to reflect the new unified private personal details form introduced in Replace individual private detail edit pages with unified form + magic code #87928
  • The PR replaces individual edit pages (legal name, DOB, phone, address) with a single form that requires magic code verification when changes are made
  • Updates Account-Settings.md and Update-Your-Expensify-Card-Mailing-Address.md to describe the new flow

Changed articles

  • docs/articles/new-expensify/settings/Account-Settings.md — Updated "Personal Information" and "Display or Legal Name" sections
  • docs/articles/new-expensify/expensify-card/Update-Your-Expensify-Card-Mailing-Address.md — Updated legal name and phone number update steps to include magic code confirmation

Update Account-Settings and Update-Your-Expensify-Card-Mailing-Address
articles to reflect the new unified personal details form with magic
code verification, replacing references to individual edit pages.

Co-authored-by: Jasper Huang <jasperhuangg@users.noreply.github.com>
@MelvinBot MelvinBot added the HelpDot Apply this label if the issue relates to ExpensifyHelp label May 15, 2026
@stephanieelliott stephanieelliott self-assigned this May 20, 2026
@stephanieelliott stephanieelliott marked this pull request as ready for review May 20, 2026 01:13
@stephanieelliott stephanieelliott self-requested a review as a code owner May 20, 2026 01:13
@github-actions
Copy link
Copy Markdown
Contributor

HelpDot Documentation Review

Overall Assessment

This PR updates two help articles to reflect a new unified personal details form with magic code verification. The changes are small and focused: adding a verification step, updating field references, and adjusting navigation language. The modifications are well-scoped and maintain consistency with the existing article structure.

Scores Summary

  • Readability: 8/10 - Steps are clear and sequential. The phrase "on the personal details form" is repeated across multiple steps and feels slightly redundant, but overall the instructions are easy to follow.
  • AI Readiness: 8/10 - Both files already have proper YAML metadata (including internalScope), task-based headings, and correct heading hierarchy. No changes to headings or metadata were made in this PR, and none were needed. The new step content uses feature-specific language that supports retrieval.
  • Style Compliance: 7/10 - Generally good UI element referencing with bold formatting. A few items need attention (see findings below).

Key Findings

Issues to address:

  1. Inconsistent field name casing (Account-Settings.md): The old version used "Legal Name" and "Date of Birth" (title case), and the new version changes these to "Legal name" and "Date of birth" (sentence case). Per HELPSITE_NAMING_CONVENTIONS.md, UI element names must match the exact text shown in the product UI. Please verify the actual UI uses sentence case for these labels. If it does, the change is correct; if not, revert to matching the UI exactly.

  2. Vague phrasing -- "unified personal details form" and "personal details form": This phrase appears three times in the diff (steps in both files). It reads more like internal terminology than something a user would recognize in the UI. Per the naming conventions, references should use the exact text shown in the product. If the UI does not label this as "personal details form," consider describing what the user actually sees (e.g., "on the form that appears" or simply removing the qualifier since the user is already on the correct page from the previous step).

  3. "Primary contact method" clarity: The phrase "enter the magic code sent to your primary contact method" appears in multiple new steps. While accurate, users may not know what their "primary contact method" is. Consider specifying "email or phone number" for clarity, or linking to documentation that explains primary contact methods.

  4. Missing Save step previously (Account-Settings.md, Personal Information section): The old version of the "Personal Information" section had no Save step -- the new version correctly adds steps 4 and 5 (Save and magic code). This is a good improvement.

Positive aspects:

  • The new magic code verification step is consistently documented across both files, which helps users who encounter it in different contexts.
  • Navigation instructions correctly use the established pattern: "in the navigation tabs (on the left on web, on the bottom on mobile)."
  • Bold formatting on UI elements is applied correctly throughout the changes.
  • Cross-links use relative paths and descriptive anchor text, following the cross-linking standards.
  • Steps remain sequential and action-oriented per the step formatting standard.

Recommendations

  1. Verify UI label casing for "Legal name," "Date of birth," "Phone number," and "Address" to ensure they match the product exactly. Consistency with the UI is the top priority per governance rules.
  2. Reconsider "personal details form" phrasing -- if this is not a UI label the user sees, replace it with what they actually see or simplify the sentence.
  3. Minor: Step 3 in "Display or Legal Name" packs multiple actions into one step ("select Legal name, update it on the personal details form, click Save, and enter the magic code to confirm"). Consider splitting this into sub-steps for scannability, consistent with how the same flow is documented in the Expensify Card article (where each action gets its own numbered step).

Files Reviewed

  • docs/articles/new-expensify/expensify-card/Update-Your-Expensify-Card-Mailing-Address.md -- Two sections updated to add magic code verification step and adjust field update language. Changes are clean and consistent.
  • docs/articles/new-expensify/settings/Account-Settings.md -- Two sections updated with new form flow and magic code step. The "Display or Legal Name" section has a dense compound step that could benefit from being broken out.

2. Select **Profile**.
3. Under **Private**, select **Phone number**.
4. Enter your updated phone number and click **Save**.
4. Update your phone number on the personal details form and click **Save**.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Naming and style: Same as above -- "on the personal details form" is not a verified UI label. Per HELPSITE_NAMING_CONVENTIONS.md, reference exact UI text. If the UI does not display this phrase, remove it or replace it with the actual label shown in the product.

2. Scroll to the **Private Details** section.
3. Update the **Legal Name**, **Date of Birth**, or **Address** fields.
2. Under **Private**, select any field (**Legal name**, **Date of birth**, **Phone number**, or **Address**).
3. Update the fields you want to change on the unified personal details form.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Naming and style: "unified personal details form" is not an exact UI label. Per HELPSITE_NAMING_CONVENTIONS.md, do not invent or generalize UI element names. Use the exact text shown in the product. Consider simplifying to something like: "Update the relevant fields." or reference the actual UI label if one exists.

1. Go to **Account > Profile**.
2. For display name: Click **Display Name**, enter your preferred name, and click **Save**.
3. For legal name: Scroll to **Private Details**, click **Legal Name**, update it, and click **Save**.
3. For legal name: Under **Private**, select **Legal name**, update it on the personal details form, click **Save**, and enter the magic code to confirm.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Readability / structure: This step chains too many actions into a single numbered step (select, update, save, enter magic code). Per HELP_AUTHORING_GUIDELINES.md Section 5, steps must be sequential, clear, and action-oriented. Break this into separate numbered steps, similar to how the "Personal Information" section above handles it.

Also, "on the personal details form" is not a verified UI label (same naming concern flagged above).

2. Under **Private**, select any field (**Legal name**, **Date of birth**, **Phone number**, or **Address**).
3. Update the fields you want to change on the unified personal details form.
4. Click **Save**.
5. If any field was changed, enter the magic code sent to your primary contact method to confirm the update.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Readability / structure: "If any field was changed" introduces unnecessary conditionality. The user just performed the update in the preceding steps, so this step will always apply. Per HELPSITE_NAMING_CONVENTIONS.md (Deterministic Writing Rule), be literal and avoid hedging. Consider rephrasing to: "Enter the magic code sent to your primary contact method to confirm the update."

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

HelpDot Apply this label if the issue relates to ExpensifyHelp

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants