diff --git a/docs/HELPSITE_NAMING_CONVENTIONS.md b/docs/HELPSITE_NAMING_CONVENTIONS.md index c7dc9e8a91ae..54d6fb68a546 100644 --- a/docs/HELPSITE_NAMING_CONVENTIONS.md +++ b/docs/HELPSITE_NAMING_CONVENTIONS.md @@ -2,15 +2,17 @@ ## Purpose -This document defines mandatory rules for referencing UI elements, buttons, tabs, icons, menus, and navigation patterns in Expensify HelpDot articles. +This document defines mandatory rules for referencing UI elements, buttons, tabs, icons, menus, colors, and navigation patterns in Expensify HelpDot articles. + +**Source of truth:** `src/languages/en.ts` and the production UI. All HelpDot articles must comply. -This document governs UI language conventions. It does not define article structure or Markdown formatting rules. Those are defined in: +This document governs UI language and capitalization conventions. It does not define article structure or Markdown formatting rules. Those are defined in: docs/HELP_AUTHORING_GUIDELINES.md -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. +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. Heading capitalization is defined in [Article Titles and Headings](#article-titles-and-headings) below. --- @@ -27,153 +29,328 @@ When referencing UI elements: If the UI changes, this document must be updated. ---- +## Actions + +### Select or choose + +Use the verb that matches the action, not the device. + +| Verb | Use when | Example | +| --- | --- | --- | +| **select** | Default for interacting with any UI element. Works across web, mobile, touch, mouse, and keyboard. | Select **Save**. | +| **choose** | The member is making a decision between multiple options, not activating a UI element. | Choose **Vendor bill** or **Journal entry**. | + +> **Examples:** +> +> Correct: +> +> - Select **Workspaces**. +> - Select **Next**. +> - Choose a default currency. +> +> Incorrect: +> +> - Click **Save**. +> - Tap **Next**. +> - Choose **Save**. (use **select** — this activates a button, not a decision) +> - Hit, press, or push a button. -# Button Naming Standards +## Button Naming Standards -## Formatting Requirements +### Bolded and matches the UI exactly - Bold all button names using **bold formatting**. -- Use Sentence case (match the UI exactly). +- Use sentence case (match the UI exactly). - Do not wrap button names in quotation marks. - Do not alter capitalization. - Do not substitute synonyms. -Correct: -- Click **Save**. -- Select **Confirm**. -- Tap **Next**. - -Incorrect: -- Click Save. -- Click “Save”. -- Click **SAVE**. -- Select confirm. -- Click **Continue** (when the button is **Next**). +> **Examples:** +> +> Correct: +> +> - Select **Save**. +> - Select **Confirm**. +> - Select **Next**. +> +> Incorrect: +> +> - Select Save. +> - Select “Save”. +> - Select **SAVE**. +> - Confirm your selection --- -# Tab Naming Standards +## Navigation Tabs + +### The LHN is referred to as "the navigation tabs" + +The primary navigation (**Home**, **Inbox**, **Spend**, **Workspaces**, **Account**) is called the **navigation tabs**. -- Bold all tab names using **bold formatting**. -- Use the exact tab name shown in the UI. +- Use "in the navigation tabs" only when you need to reference the primary navigation directly. +- Bold each tab name and use the exact name shown in the UI. - Do not wrap tab names in quotation marks. - Do not paraphrase tab names. +- Only use these position descriptions. Do not use any other position wording. + - **(on the left on web, on the bottom on mobile)**: Use when members may need help finding the tabs on both platforms. + - **In the navigation tabs on the left**: Use in web-only instructions. + - **In the navigation tabs on the bottom**: Use in mobile-only instructions. + +> **Examples:** +> +> Correct: +> +> - In the navigation tabs (on the left on web, on the bottom on mobile), select **Workspaces**. +> - [if web-only] In the navigation tabs on the left, select **Workspaces**. +> - [if mobile-only] In the navigation tabs on the bottom, select **Workspaces**. +> +> Incorrect: +> +> - On the navigation tabs +> - Open Workspace (when the tab is **Workspaces**). +> - Tap **Spend** from the navigation tabs on the bottom +> - Select **Spend** in the left sidebar. -Correct: -- Select **Chat**. -- Open **Workspaces**. -- Go to **Settings**. +--- -Incorrect: -- Select “Chat”. -- Go to Chat. -- Open Workspace (when the tab is **Workspaces**). +## Navigation Paths + +### Workspaces > [workspace name] > Members + +Use a navigation path instead of naming the navigation menu. + +- Start the path with the navigation tab. +- Separate each level with `>`. +- Bold the entire path. +- Capitalize each segment exactly as it appears in the UI. +- Include a lowercase bracketed placeholder for variable names: **[workspace name]**, **[domain name]**. + +> **Examples:** +> +> Correct: +> +> - Select **Workspaces > [workspace name] > Members**. +> - Select **Spend > Expenses**. +> - Select **Account > Settings**. +> - Navigate to **Spend > Reports**. +> +> Incorrect: +> +> - Select **Workspaces > Members**. (include the placeholder) +> - Select **Workspaces > [Workspace Name] > Members**. (lowercase the placeholder) +> - In the workspace menu, select **Members**. +> - In the Spend sidebar, select **Expenses**. +> - Open the settings menu and select **Preferences**. +> - Select **Workspaces**, then **[workspace name]**, then **Members**. (use a path) + +## Navigation Menu + +### The menu nested under the LHN is the "navigation menu" + +The **navigation menu** is the secondary menu inside a navigation tab, such as the list of **Members**, **Workflows**, and **Categories** inside a workspace. Use this name on all platforms. + +- Prefer a navigation path. Only reference the navigation menu directly if continuing previous steps where a navigation path was already provided. +- Do not call it the sidebar, workspace, account menu, etc. + +> **Examples:** +> +> Correct: +> +> - In the navigation menu, select **Rules**. +> - In the navigation menu, select **Subscription**. +> +> Incorrect: +> +> - Inside your workspace, select **Rules**. +> - Go to Subscription under **Account**. +> - In the workspace sidebar, select **Workflows**. --- -# Three Dots Menu Rule - -When referencing the three dots menu, always write: +## Three Dots Menu -Select the three dots **(⋮)**. +### Select **More (⋮)** -Formatting requirements: +When referencing the three dots menu, always write: Select **More (⋮)** - Always include the visual symbol inside parentheses: **(⋮)** - Always bold the symbol. -- Always include the words “three dots” before the symbol. +- Always include the word “**More**” before the symbol. - Do not wrap in quotation marks. -Correct: -- Select the three dots **(⋮)**. -- Click the three dots **(⋮)** next to the expense. - -Incorrect: -- Tap the three dots -- Open the three dots menu -- Click ⋮ +> **Examples:** +> +> Correct: +> +> - Select **More (⋮)**. +> - Select **More (⋮)** next to the workspace. +> +> Incorrect: +> +> - Tap the three dots (⋮) +> - Open the three dots menu +> - Click ⋮ --- -# Navigation Instruction Standards - -Follow the platform decision hierarchy below. +## Platform Instructions + +### If web and mobile navigation are the same, combine instructions + +Write one set of instructions. Do not duplicate steps. + +> **Example:** +> +> - In the navigation tabs (on the left on web, on the bottom on mobile), select **Workspaces > [workspace name] > Members**. + +### If web and mobile navigation differ, provide separate labeled instructions + +> **Example:** +> +> On web: +> +> 1. In the navigation tabs on the left, select **Spend > Insights > Top spenders**. +> +> On mobile: +> +> 1. In the navigation tabs on the bottom, select **Spend**. +> 2. Select the navigation menu to open it. +> 3. Select **Insights**. + +**If a feature isn't available on a platform**, name the platform where it is available, not the device or channel. Use **web** and **mobile**, not “Web,” “website,” “desktop,” or "app" on their own. + +> **Examples:** +> +> Correct: +> +> - This feature is only available on web. It isn't available on mobile. +> - This feature is only available on mobile. It isn’t available on web. +> +> Incorrect: +> +> - This feature is only available on the web. +> - Use the website to do this. +> - This isn't supported on desktop. +> - Manage this from web. --- -## If Web and Mobile Navigation Differ +## Toggle References -Provide separate instructions. +### Use the exact UI label and say "enable" or "disable" when adjusting -Web: -In the navigation tabs on the left. - -Mobile: -In the navigation tabs on the bottom. - -Do not merge these into one sentence. +- Refer to a toggle using its exact label shown in the UI. +- Bold toggle names if they appear as clickable UI elements. +- Do not reword toggle labels. +- Toggle actions are limited to "enable" or "disable." + +> **Examples:** +> +> Correct: +> +> - Enable **Per diem**. +> - Disable **Company cards**. +> +> Incorrect: +> +> - Turn on **Per Diem** +> - Disable the Company Cards toggle --- -## If Web and Mobile Navigation Are Structurally the Same - -Use a unified sentence: - -In the navigation tabs (on the left on web, on the bottom on mobile). +## Section References -Do not duplicate instructions unnecessarily. +- Use the exact section header text shown in the UI. +- Do not generalize section names. +- Do not paraphrase. --- -## Hamburger Menu Rule (Mobile Only) +## Name UI Elements by Function -If access requires the hamburger menu, always write: +### Name UI elements by what they do, not what they look like or where they happen to be -On mobile, tap the hamburger menu in the top-left corner, then select **[Tab name]**. +| Write | Not | +| --- | --- | +| Search icon | magnifying glass | +| Delete icon | trash can | +| selection bar | the bar at the bottom, the bulk selection bar | +| navigation menu | hamburger menu, three lines, sidebar | -Rules: +--- -- Do not paraphrase this sentence. -- Always specify “top-left corner”. -- Always bold the tab name. -- Do not use quotation marks. +## Fields + +### Use **field** for any text-entry control, including search boxes, text boxes, and inputs + +- Bold the field's label and follow it with "field." +- Use the exact label shown in the UI. +- For the search control, write "search field" (lowercase, not bold) unless it has a visible label. + +> **Examples:** +> +> Correct: +> +> - Enter a comment in the **Description** field. +> - Enter the merchant name in the **Merchant** field. +> - Type the member's name in the search field. +> +> Incorrect: +> +> - Type in the Description box. +> - Fill in the Merchant input. +> - Use the search bar. +> - Enter a value in the text box. --- -## If a Feature Is Not Available on Mobile +## Bulk Actions Menu -State clearly: +### The bulk actions menu is called the "selection bar" -This feature is not available on mobile. +- Call it the selection bar (lowercase). +- Do not bold the menu name. +- Do not describe its position or color. -Do not soften or imply this limitation. +> **Examples:** +> +> Correct: +> +> - Select the reports, then select **Export** from the selection bar. +> - Select the expenses, then select **Delete** from the selection bar. +> +> Incorrect: +> +> - Select the reports, then select **Export** from the bar at the bottom. +> - Use the bulk actions menu to export. +> - Select the checkbox, then select the green button. --- -# Section and Toggle References - -## Sections +## Color References -- Use the exact section header text shown in the UI. -- Do not generalize section names. -- Do not paraphrase. - ---- - -## Toggles +### Only reference color when required as a secondary descriptor -- Use the exact toggle label shown in the UI. -- Bold toggle names if they appear as clickable UI elements. -- Do not reword toggle labels. +Don't use color as the only way to identify a UI element. When color communicates meaningful status, include it as a secondary descriptor alongside the element name. -Example: -- Enable **Reimbursements**. -- Turn on **Company Cards**. +> **Examples:** +> +> Correct: +> +> - Select the company card with the red dot. +> - A red dot means there’s a connection error. +> - When a request is pending, a green dot appears next to **Domain admins**. +> +> Incorrect: +> +> - Click the green receipt button +> - Group participants are listed with a green checkmark. +> - Look for the green button at the top. --- -# Cross-Platform Clarity Rule +## Cross-Platform Clarity Rule When platform differences impact behavior: @@ -187,11 +364,11 @@ If UI text differs between platforms: If layout differs but labels are identical: -- Follow the Navigation Instruction Standards. +- Follow the [Platform Instructions](#platform-instructions) rules. --- -# Prohibited Language +## Prohibited Language Do not use vague navigation phrases: @@ -202,7 +379,154 @@ Do not use vague navigation phrases: - “Find the setting” - “The options button” -Always reference the exact UI label or icon. +Always reference the exact UI label, icon, or navigation path. + +--- + +# Writing and Capitalization + +## Core Capitalization Rules + +- Use title case for article titles. +- Use sentence case everywhere else. +- When referring to UI elements, match the UI casing exactly. +- Use all caps for acronyms. +- When quoting the UI, match its capitalization exactly. +- Capitalize branded names as defined in [src/languages/en.ts](https://github.com/Expensify/App/blob/main/src/languages/en.ts). +- Capitalize proper nouns. + +> **Examples:** +> +> Correct: +> +> - BYOC +> - Select **Add approval workflow** +> +> Incorrect: +> +> - Byoc +> - Select **Add Approval Workflow** + +--- + +## Article Titles and Headings + +- Use title case for the article title: the metadata `title` and the `#` title. +- Use sentence case for every `##` heading. +- Capitalize proper nouns and product names inside headings. +- `# FAQ` is always written in all caps as an acronym. + +> **Examples:** +> +> Correct: +> +> - `# Configure NetSuite Settings in Expensify` +> - `## Who can configure NetSuite settings` +> +> Incorrect: +> +> - `# Configure NetSuite settings in Expensify` +> - `## Who Can Configure NetSuite Settings` + +--- + +## Roles + +### Capitalize roles only when quoting a UI label + +- Use lowercase roles in running text. +- Capitalize a role only when quoting a UI label. +- Do not capitalize a role to signal importance. + +**Role names:** + +- workspace admin +- workspace owner +- domain admin +- account manager +- account executive +- partner manager +- member + +> **Examples:** +> +> Correct: +> +> - Only the workspace owner can manage the payment card. +> - Ask your domain admin to add the domain. +> - Chat with your account manager. +> - Choose **Workspace admin** from the list of roles. +> +> Incorrect: +> +> - Only the Workspace Owner can manage the payment card. +> - Only the Workspace owner can manage the payment card. +> - Ask your Domain Admin to add the domain. + +--- + +## Generic Terms + +### Always lowercase, except when referencing a UI label directly + +Lowercase these in running text, even when the matching tab is capitalized: + +- workspace / workspaces +- report / reports +- expense / expenses +- expense report +- invoice / invoices +- company card / company cards +- per diem / per diem rates +- workflow / approval workflow +- subscription +- plan +- cash back +- realtime +- expense management +- spend management +- bill pay + +> **Examples:** +> +> Correct: +> +> - Each workspace has one workspace owner. +> - You can configure how company card purchases export. +> - Set per diem rates to control daily employee spend. +> +> Incorrect: +> +> - Every Workspace has one Workspace Owner. +> - You can configure Company Card purchases export. +> - Set Per Diem rates. +> - Use Bill Pay to pay vendors. + +--- + +## Plans and Subscriptions + +### Capitalize plan names + +- Capitalize the plan name. Lowercase the word "plan." +- Lowercase subscription types in running text. +- Match the UI when quoting subscription options. + +> **Examples:** +> +> Correct: +> +> - Upgrade to the Control plan. +> - Your workspace is on the Collect plan. +> - Sign up for an annual subscription. +> - Select **Annual** or **Pay-per-use**. +> +> Incorrect: +> +> - Upgrade to the Control Plan. +> - Your workspace is on the control plan. +> - Sign up for an Annual Subscription. +> - Select annual or pay-per-use. --- diff --git a/docs/HELP_AUTHORING_GUIDELINES.md b/docs/HELP_AUTHORING_GUIDELINES.md index 97a273ea11c5..e7f54a4dad05 100644 --- a/docs/HELP_AUTHORING_GUIDELINES.md +++ b/docs/HELP_AUTHORING_GUIDELINES.md @@ -15,6 +15,7 @@ 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 @@ -46,10 +47,19 @@ If multiple workflows are detected → split into multiple articles. - 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 +# 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 @@ -69,7 +79,7 @@ Every article must begin with: ```yaml --- -title: Clear task-based title using feature name +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] @@ -106,6 +116,11 @@ Step instructions must be: - 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 @@ -277,6 +292,16 @@ Before outputting an article, confirm: - 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 diff --git a/docs/HELP_AUTHORING_GUIDELINES_TASK.md b/docs/HELP_AUTHORING_GUIDELINES_TASK.md index bbfa90bb58ff..bc629dfc5c11 100644 --- a/docs/HELP_AUTHORING_GUIDELINES_TASK.md +++ b/docs/HELP_AUTHORING_GUIDELINES_TASK.md @@ -7,7 +7,7 @@ Task articles explain how to complete a specific workflow in Expensify. Task articles answer questions such as: * How do I submit an expense? -* How do I change my Workspace plan? +* How do I change my workspace plan? * How do I connect NetSuite? * Why can't I complete a specific action? @@ -22,7 +22,7 @@ Every task article must: * Solve one primary workflow only * Match a specific customer goal * Use exact UI terminology -* Follow the official naming conventions +* Follow the official naming conventions in docs/HELPSITE_NAMING_CONVENTIONS.md * Be optimized for semantic retrieval * Be concise, actionable, and easy to scan @@ -89,7 +89,7 @@ Every task article must include: ```yaml --- -title: Clear task-based title using the feature name +title: Clear Task-Based Title Using the Feature Name (title case) description: Short summary of the workflow and outcome keywords: [primary task phrase, feature name, related search terms] internalScope: Audience is [target role]. Covers [workflow]. Does not cover [excluded workflows]. @@ -110,6 +110,7 @@ Task article headings must: * Be searchable * Be explicit * Describe what the reader will do or learn +* Use title case for the article title and sentence case for every `##` heading Use headings that begin with: @@ -122,7 +123,7 @@ Use headings that begin with: Examples: -* How to change your Workspace plan +* How to change your workspace plan * Where to find billing receipts * Why you can't submit an expense report * What happens after you approve an expense @@ -146,6 +147,9 @@ Procedural sections must: * Follow the actual UI flow * Use exact UI labels * Present actions in sequence +* Use **select** for UI interactions and **choose** only for decisions between options +* 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, and use separate "On web:" and "On mobile:" instructions when it differs Instructions should: @@ -262,6 +266,8 @@ Before publishing, confirm: * One primary workflow is covered * Headings are task-based * UI terminology matches the product +* The article title uses title case and every `##` heading uses sentence case +* UI references, navigation, and capitalization follow docs/HELPSITE_NAMING_CONVENTIONS.md * Navigation instructions are accurate * Steps follow the actual workflow * Metadata reflects search intent diff --git a/docs/HELP_AUTHORING_GUIDELINES_TOPIC.md b/docs/HELP_AUTHORING_GUIDELINES_TOPIC.md index 08a5d461f66d..1bad4f0d6809 100644 --- a/docs/HELP_AUTHORING_GUIDELINES_TOPIC.md +++ b/docs/HELP_AUTHORING_GUIDELINES_TOPIC.md @@ -9,7 +9,7 @@ They help customers understand concepts before they perform related tasks. Topic articles answer questions such as: * How does billing work? -* What is a Workspace? +* What is a workspace? * How do approvals work? * How do reimbursements work? * How do subscription plans work? @@ -25,7 +25,7 @@ Every Topic article must: * Explain one product concept or product area. * Match a specific customer question. * Use exact product terminology. -* Follow the official naming conventions. +* Follow the official naming conventions in docs/HELPSITE_NAMING_CONVENTIONS.md. * Be optimized for semantic retrieval. * Be concise, organized, and easy to scan. @@ -94,7 +94,7 @@ Every Topic article must include: ```yaml --- -title: Clear concept-based title using the feature name +title: Clear Concept-Based Title Using the Feature Name (title case) description: Short summary of the concept keywords: [primary concept, feature name, related search terms] internalScope: Audience is [target role]. Covers [concept]. Does not cover [excluded workflows or concepts]. @@ -111,6 +111,8 @@ Metadata should reflect realistic customer search behavior. Topic headings should answer customer questions about the concept. +Use title case for the article title and sentence case for every `##` heading. + Prefer headings beginning with: * How @@ -267,6 +269,8 @@ Before publishing, confirm: * Common scenarios receive the most attention. * Important terminology is used consistently. * UI terminology matches the product. +* The article title uses title case and every `##` heading uses sentence case. +* UI references, navigation, and capitalization follow docs/HELPSITE_NAMING_CONVENTIONS.md. * Metadata reflects customer search intent. * Cross-links are minimal and purposeful. * Every suggested screenshot has a clear purpose that prevents or resolves a specific member confusion. diff --git a/docs/TEMPLATE-task.md b/docs/TEMPLATE-task.md index cadafe8f0e48..ddb60449438d 100644 --- a/docs/TEMPLATE-task.md +++ b/docs/TEMPLATE-task.md @@ -3,14 +3,12 @@ Task articles should describe things the user intentionally does. Outcomes, consequences, and eligibility rules belong inside those task articles or in related topic articles. --- -title: Clear task-based title using the feature name +title: Clear Task-Based Title Using the Feature Name (title case) 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]. contentType: task platform: [platform value] -contentType: topic -platform: [platform] --- @@ -50,7 +50,7 @@ Avoid marketing language, implementation details, and unnecessary UI narration. --- -## Who can use [Feature Name] +## Who can use [feature name] State only the information the reader needs: @@ -61,13 +61,13 @@ State only the information the reader needs: If another workflow must be completed first, link to it using a relative link. -If unavailable on mobile, state: +If unavailable on a platform, name the platform where it is available: -This feature is not available on mobile. +This feature is only available on web. It isn't available on mobile. --- -## How to [Complete Primary Task] +## How to [complete primary task] Keep the steps focused. @@ -75,7 +75,14 @@ Describe only the actions necessary to complete the task. Do not document every click if it doesn't help the reader. -If web and mobile differ, separate the instructions. +Use **select** for UI interactions and **choose** only for decisions between options. + +Start navigation in the navigation tabs with a bolded navigation path: + +1. In the navigation tabs (on the left on web, on the bottom on mobile), select **Workspaces > [workspace name] > [Section name]**. +2. Select **[Exact button name, matching the UI]**. + +If web and mobile differ, separate the instructions under "On web:" and "On mobile:". If they're identical, combine them. @@ -93,7 +100,7 @@ Include this section only when the workflow changes behavior or has important co --> -## What happens after you [Complete Task] +## What happens after you [complete task] Explain what changes after completing the workflow. diff --git a/docs/TEMPLATE-topic.md b/docs/TEMPLATE-topic.md index 5b31501873eb..3f23e8c1425f 100644 --- a/docs/TEMPLATE-topic.md +++ b/docs/TEMPLATE-topic.md @@ -3,7 +3,7 @@ Topic articles explain a single product concept, feature, or behavior. They provide the context members need to understand related tasks by explaining the permissions, prerequisites, rules, and concepts that apply across those tasks, while leaving step-by-step instructions to individual Task articles. --- -title: [Natural, searchable topic title] +title: [Natural, Searchable Topic Title in Title Case] description: Briefly summarize the concept and why it matters. keywords: [[primary topic], [feature name], [related search phrases]] internalScope: Audience is [target audience]. Covers [single concept or feature]. Does not cover [related tasks or adjacent concepts]. @@ -48,12 +48,16 @@ TITLE GUIDELINES Choose a natural, searchable title that clearly describes the concept using the product's terminology. +Use title case for the title. Use sentence case for every ## heading. + +Follow docs/HELPSITE_NAMING_CONVENTIONS.md for UI references, navigation, and capitalization. + Examples: -- Billing and subscriptions -- Annual subscriptions -- Workspace roles -- Approval workflows +- Billing and Subscriptions +- Annual Subscriptions +- Workspace Roles +- Approval Workflows Avoid: @@ -68,11 +72,11 @@ Titles may: Examples: -- Billing and subscriptions -- Billing issues -- Annual subscriptions -- Workspace roles -- Understand approval workflows +- Billing and Subscriptions +- Billing Issues +- Annual Subscriptions +- Workspace Roles +- Understand Approval Workflows Avoid: diff --git a/docs/TEMPLATE.md b/docs/TEMPLATE.md index b7e0dfb0d4ba..14ea86841c60 100644 --- a/docs/TEMPLATE.md +++ b/docs/TEMPLATE.md @@ -1,5 +1,5 @@ --- -title: Clear task-based title using the feature name +title: Clear Task-Based Title Using the Feature Name (title case) description: A short description of the page's content. This is used for SEO purposes. keywords: [how to primary task, feature name, related task phrases] internalScope: Audience is [who this doc is for]. Covers [single clearly defined workflow], does not cover [closely related workflows intentionally excluded]. @@ -7,6 +7,7 @@ internalScope: Audience is [who this doc is for]. Covers [single clearly defined -1. Go to Settings > Workspaces > Workspace Name > [Section Name]. -2. Click **[Exact button name in Sentence case]**. +1. In the navigation tabs (on the left on web, on the bottom on mobile), select **Workspaces > [workspace name] > [Section name]**. +2. Select **[Exact button name, matching the UI]**. 3. Configure the required settings. -4. Click **Save** or final action button (for example, **Submit**, **Confirm**). +4. Select **Save** or the final action button (for example, **Submit**, **Confirm**). **ADD A SCREENSHOT HERE.** Suggestion: Show the full page with the relevant section highlighted. @@ -114,9 +118,9 @@ Clear direct answer. ## Why can’t I see [Feature Name]? Explain possible causes: -- You’re not a Workspace Admin or Workspace Owner +- You’re not a workspace admin or workspace owner - The feature is not included in your plan -- The Workspace setting is disabled +- The workspace setting is disabled - Domain-level restrictions apply ## Does [Feature Name] work with [Integration or Related Feature]?