diff --git a/.github/workflows/on_pull_request_supabase.yml b/.github/workflows/on_pull_request_supabase.yml index a7f5e9c744..b66e0ca7c3 100644 --- a/.github/workflows/on_pull_request_supabase.yml +++ b/.github/workflows/on_pull_request_supabase.yml @@ -5,7 +5,7 @@ on: types: [opened, synchronize, reopened, ready_for_review] jobs: - test: + on-pull-request-supabase: runs-on: ubuntu-latest env: diff --git a/apps/backend/supabase/schema.gen.ts b/apps/backend/supabase/schema.gen.ts index d9b31fc501..f5969a4398 100644 --- a/apps/backend/supabase/schema.gen.ts +++ b/apps/backend/supabase/schema.gen.ts @@ -34,340 +34,13 @@ export interface Database { } public: { Tables: { - assistant_threads: { - Row: { - created_at: string - id: number - openai_thread_id: string | null - slack_thread_ts: string | null - } - Insert: { - created_at?: string - id?: number - openai_thread_id?: string | null - slack_thread_ts?: string | null - } - Update: { - created_at?: string - id?: number - openai_thread_id?: string | null - slack_thread_ts?: string | null - } - Relationships: [] - } - page: { - Row: { - checksum: string | null - id: number - last_refresh: string | null - meta: Json | null - parent_page_id: number | null - path: string - source: string | null - type: string | null - version: string | null - } - Insert: { - checksum?: string | null - id?: number - last_refresh?: string | null - meta?: Json | null - parent_page_id?: number | null - path: string - source?: string | null - type?: string | null - version?: string | null - } - Update: { - checksum?: string | null - id?: number - last_refresh?: string | null - meta?: Json | null - parent_page_id?: number | null - path?: string - source?: string | null - type?: string | null - version?: string | null - } - Relationships: [ - { - foreignKeyName: "page_parent_page_id_fkey" - columns: ["parent_page_id"] - isOneToOne: false - referencedRelation: "page" - referencedColumns: ["id"] - } - ] - } - page_section: { - Row: { - content: string | null - embedding: string | null - heading: string | null - id: number - page_id: number - slug: string | null - token_count: number | null - } - Insert: { - content?: string | null - embedding?: string | null - heading?: string | null - id?: number - page_id: number - slug?: string | null - token_count?: number | null - } - Update: { - content?: string | null - embedding?: string | null - heading?: string | null - id?: number - page_id?: number - slug?: string | null - token_count?: number | null - } - Relationships: [ - { - foreignKeyName: "page_section_page_id_fkey" - columns: ["page_id"] - isOneToOne: false - referencedRelation: "page" - referencedColumns: ["id"] - } - ] - } - queries: { - Row: { - created_at: string - id: number - query_string: string | null - type: string | null - } - Insert: { - created_at?: string - id?: number - query_string?: string | null - type?: string | null - } - Update: { - created_at?: string - id?: number - query_string?: string | null - type?: string | null - } - Relationships: [] - } - story: { - Row: { - created_at: string - id: number - name: string | null - storybook_id: string | null - } - Insert: { - created_at?: string - id?: number - name?: string | null - storybook_id?: string | null - } - Update: { - created_at?: string - id?: number - name?: string | null - storybook_id?: string | null - } - Relationships: [] - } - story_render: { - Row: { - actual_duration: number | null - base_duration: number | null - commit_sha: string | null - core_version_number: string | null - id: number - phase: string | null - run_at: string - story_id: number | null - } - Insert: { - actual_duration?: number | null - base_duration?: number | null - commit_sha?: string | null - core_version_number?: string | null - id?: number - phase?: string | null - run_at?: string - story_id?: number | null - } - Update: { - actual_duration?: number | null - base_duration?: number | null - commit_sha?: string | null - core_version_number?: string | null - id?: number - phase?: string | null - run_at?: string - story_id?: number | null - } - Relationships: [ - { - foreignKeyName: "story_render_story_id_fkey" - columns: ["story_id"] - isOneToOne: false - referencedRelation: "story" - referencedColumns: ["id"] - } - ] - } + [_ in never]: never } Views: { [_ in never]: never } Functions: { - get_page_parents: { - Args: { - page_id: number - } - Returns: { - id: number - parent_page_id: number - path: string - meta: Json - }[] - } - hnswhandler: { - Args: { - "": unknown - } - Returns: unknown - } - ivfflathandler: { - Args: { - "": unknown - } - Returns: unknown - } - match_discussions: { - Args: { - embedding: string - match_threshold: number - match_count: number - min_content_length: number - } - Returns: { - path: string - content: string - similarity: number - source: string - type: string - meta: Json - heading: string - slug: string - }[] - } - match_page_sections: { - Args: { - embedding: string - match_threshold: number - match_count: number - min_content_length: number - } - Returns: { - id: number - page_id: number - slug: string - heading: string - content: string - similarity: number - }[] - } - match_page_sections_for_ai: { - Args: { - embedding: string - match_threshold: number - match_count: number - min_content_length: number - } - Returns: { - path: string - content: string - similarity: number - }[] - } - match_page_sections_v3: { - Args: { - embedding: string - match_threshold: number - match_count: number - min_content_length: number - } - Returns: { - path: string - content: string - similarity: number - source: string - type: string - meta: Json - heading: string - slug: string - }[] - } - match_weekly_search_usage: { - Args: Record - Returns: { - query_string: string - count: number - }[] - } - upsert_story_and_create_story_render: { - Args: { - _storybook_id: string - _story_name: string - _actual_duration: number - _base_duration: number - _commit_sha: string - _core_version: string - _phase: string - } - Returns: undefined - } - vector_avg: { - Args: { - "": number[] - } - Returns: string - } - vector_dims: { - Args: { - "": string - } - Returns: number - } - vector_norm: { - Args: { - "": string - } - Returns: number - } - vector_out: { - Args: { - "": string - } - Returns: unknown - } - vector_send: { - Args: { - "": string - } - Returns: string - } - vector_typmod_in: { - Args: { - "": unknown[] - } - Returns: number - } + [_ in never]: never } Enums: { [_ in never]: never diff --git a/packages/paste-website/src/pages/api/create-component-perf-metric.ts b/packages/paste-website/src/pages/api/create-component-perf-metric.ts index 841330713d..6d507e06f6 100644 --- a/packages/paste-website/src/pages/api/create-component-perf-metric.ts +++ b/packages/paste-website/src/pages/api/create-component-perf-metric.ts @@ -1,5 +1,5 @@ /* eslint-disable camelcase */ -import { createClient } from "@supabase/supabase-js"; +// import { createClient } from "@supabase/supabase-js"; import dogapi from "dogapi"; import type { NextApiRequest, NextApiResponse } from "next"; import Rollbar from "rollbar"; @@ -107,27 +107,31 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse) logger.info(`${LOG_PREFIX} Valid request body: ${JSON.stringify(perfMetric.data)}`); - logger.info(`${LOG_PREFIX} Save metric to Supabase`); - - const supabaseClient = createClient(SUPABASE_URL, SUPABASE_KEY); - const { error } = await supabaseClient.rpc("upsert_story_and_create_story_render", { - _storybook_id: perfMetric.data.id, - _story_name: perfMetric.data.kind, - _actual_duration: perfMetric.data.actualDuration, - _base_duration: perfMetric.data.baseDuration, - _commit_sha: perfMetric.data.commitSha, - _core_version: perfMetric.data.coreVersionNumber, - _phase: perfMetric.data.phase, - }); - - if (error) { - logger.error(`${LOG_PREFIX} Error upserting story and creating story render`, { error }); - rollbar.error(`${LOG_PREFIX} Error upserting story and creating story render`, { error }); - res.status(500).json({ error: "Error upserting story and creating story render", details: error }); - return; - } - - logger.info(`${LOG_PREFIX} Saved metric to Supabase`); + /* + * logger.info(`${LOG_PREFIX} Save metric to Supabase`); + * + * const supabaseClient = createClient(SUPABASE_URL, SUPABASE_KEY); + * + * const { error } = await supabaseClient.rpc("upsert_story_and_create_story_render", { + * _storybook_id: perfMetric.data.id, + * _story_name: perfMetric.data.kind, + * _actual_duration: perfMetric.data.actualDuration, + * _base_duration: perfMetric.data.baseDuration, + * _commit_sha: perfMetric.data.commitSha, + * _core_version: perfMetric.data.coreVersionNumber, + * _phase: perfMetric.data.phase, + * }); + * + * + * if (error) { + * logger.error(`${LOG_PREFIX} Error upserting story and creating story render`, { error }); + * rollbar.error(`${LOG_PREFIX} Error upserting story and creating story render`, { error }); + * res.status(500).json({ error: "Error upserting story and creating story render", details: error }); + * return; + * } + * + * logger.info(`${LOG_PREFIX} Saved metric to Supabase`); + */ logger.info(`${LOG_PREFIX} Save metric to Datadog`); diff --git a/packages/paste-website/src/pages/foundations/content/content-checklist/index.mdx b/packages/paste-website/src/pages/foundations/content/content-checklist/index.mdx index b0beda2e0a..1499d8f4e1 100644 --- a/packages/paste-website/src/pages/foundations/content/content-checklist/index.mdx +++ b/packages/paste-website/src/pages/foundations/content/content-checklist/index.mdx @@ -38,60 +38,35 @@ export const getStaticProps = async () => { -## Get content support - -### Training and resources - -Look out for information about content training sessions via email and sign up! - -Check out the latest resource: [Content for UX](https://docs.google.com/document/d/1nerpH9xhsG6obgl-nKWbzwJFQva5ZU6VdNgCRJx-zVY/edit?usp=sharing). -This contains the key takeaways from the training session, action points, and tools for you to use. - -### Quick self-serve checklist - How do you know if your content is "done" or "good"? -#### The tone is appropriate to the scenario. - -- A stressful scenario is managed empathetically, with a knowledgeable and encouraging tone. Reassure and inform the user clearly. -- A win or success is managed genuinely, with a positive and encouraging tone. Celebrate with the user genuinely. -- A repeated interaction is managed efficiently, with a positive and conversational tone. Support the user's flow by reducing friction. -- The content sounds like a frinedly specialist. +**The content meets the user's immediate needs.** +- The user can understand the context, the goal, the impact of any actions or decisions they’ll make, and knows what happens next. -#### The content meets the user's immediate needs. - -- The user has enough information to understand the context and proposition, the impact of an action/decision, and clarity over what happens next. - -#### The words and structure are as simple as they can be. - -- You've replaced jargon with a simpler term or explained technical language or acronyms. +**The words and structure are as simple as they can be.** - Sentences are short. +- You've eliminated jargon where possible, and explained technical language if it’s required. -#### The message is clear and unambiguous. - +**The message is clear and unambiguous.** - Your content can only be interpreted one way. - You've replaced any vague or imprecise language with precise, clear terms. -#### You've checked it. Twice. +**The tone is appropriate to the scenario.** +- Content generally sounds like a friendly specialist. -- Capitals, punctuation, and spelling all align with this guide. -- Tip: Read it out loud to yourself. If it doesn't "sound right", consider changing the wording or phrasing. +| Scenario | Tone | +| ------------- | ------------- | +| Stressful situation | Content provides factual information and informs the user about what they can do next. Content tone is empathetic and reassuring. | +| Successful situation | Content celebrates the user. Content tone is positive and encouraging. | +| Repeated interaction | Content reduces friction and anticipates user needs. Content tone is positive and conversational. | -#### Someone unfamiliar with the project has read and understood it. +**The content aligns with our [style guide](/foundations/content/product-style-guide) and [word list](/foundations/content/word-list).** +- Capitalization, punctuation, and terms all align with current guidance. +**Bonus: Someone unfamiliar with the project has read and understood it.** - Ask them to read it out loud, then tell you what it means. -- If their understanding matches your intent, great! Your content is clear. +- If their understanding matches your intent, your content is clear. - If they stumble on words or don't understand, ask why. Use their feedback to iterate, then try again. - - Need support with non-product content? - - {' '} - Visit the - Brand Writing Style Guidelines here - . - - - diff --git a/packages/paste-website/src/pages/foundations/content/index.mdx b/packages/paste-website/src/pages/foundations/content/index.mdx index 7be84a55e4..b5857a8ce8 100644 --- a/packages/paste-website/src/pages/foundations/content/index.mdx +++ b/packages/paste-website/src/pages/foundations/content/index.mdx @@ -39,58 +39,35 @@ export const getStaticProps = async () => { -**Use the guidance in the way that makes most sense to you.** -These content pages should help you to feel more confident in writing concise, clear, and consistent product content. -You might read [Voice and tone](/foundations/content/voice-and-tone) once for foundational understanding, while you might bookmark [Product style guide](/foundations/content/product-style-guide) for ease of reference. +## [Content checklist](/foundations/content/content-checklist) -Look out for training sessions coming soon to help you make the most of these pages. +- Feel confident in knowing when your content is "done" or "good" -## Sections at a glance — find what you need -### Voice and tone +## [Voice and tone](/foundations/content/voice-and-tone) - Understand voice and tone and their role in communicating. -- Identify and use the Twilio Voice consistently. +- Identify and use the Twilio voice consistently. - Use tone to shape the user experience. - Find the appropriate tone and approach. -- Go to [Voice and tone](/foundations/content/voice-and-tone) -### Product style guide +## [Product style guide](/foundations/content/product-style-guide) -- The core principles of our content and "how we should write." -- Punctuation guidance and exceptions. -- Formatting and grammar tips, including capitals, lists, bold/italics, numbers, acronyms, and abbreviations. -- Commonly confused or misspelled words and phrases. -- Go to [Product style guide](/foundations/content/product-style-guide) +- Understand our core content principles and "how we should write." +- Get style guidance for punctuation, formatting, and usage. -### Components (coming in Q2) +## [Word list](/foundations/content/word-list) -- Applying guidance to specific components. Covering buttons, headings, modals, navigation etc. +- Learn which words and terminology we use in our product, and which we don’t. -### Get support - -- Check and edit content yourself with prompts and guidance. -- Submit a request for content support from a UX Writer. -- Go to [Get Support](/foundations/content/content-checklist) - -## Feedback - -These guidelines rely on your feedback to evolve and grow. Please reach out on Slack with - -- Usability feedback — the more specific, the better. -- Edge cases or exceptions — send over screen shots and queries. -- Additional examples — have a great example of before/after? -- Questions and queries — if something isn't clear, let us know. - Need support with non-product content? + Got feedback? - {' '} - Visit the - Brand Writing Style Guidelines here - . - + Post to Paste Github discussions{" "} with any usability feedback, edge cases or exceptions, additional examples, or questions. + + diff --git a/packages/paste-website/src/pages/foundations/content/product-style-guide/index.mdx b/packages/paste-website/src/pages/foundations/content/product-style-guide/index.mdx index 32406d1497..f889101e53 100644 --- a/packages/paste-website/src/pages/foundations/content/product-style-guide/index.mdx +++ b/packages/paste-website/src/pages/foundations/content/product-style-guide/index.mdx @@ -40,482 +40,181 @@ export const getStaticProps = async () => { -## Content principles +## Product content principles -#### Identify your user and speak directly to them +Keep the following principles in mind when writing product content. These mirror and complement the [Twilio content principles](https://library.twilio.com/guidelines/guide/1b8c14a4-287d-47a4-8ac6-1621bfe97a6d/page/34720f98-b7f8-4436-8e66-4f814801eec1). -- Consider who you're writing for and their technical level. Use words the user is familiar with. -- Address the user as _you_, refer to Twilio as _we_. +**Identify your user and speak directly to them.** Consider who you're writing for and their technical level. Use words the user is familiar with. -#### Write for the reading level of a 10-13 year old +**Write as if the user is in a rush.** Avoid repetition and padding. Chunk content and use headings to help the user find what they need. -- Use simple, short sentences and common words. -- Explain technical terms and write acronyms in full the first time a user sees them. +**Be direct and straightforward.** Front-load content with words that address the user’s needs and provide clear instructions for how to address that need. For example “To upload a CSV, select **Upload**.” Avoid jargon, idioms, or cultural references to communicate what you mean. - - Using readability tools - - Sites offering free readability tools like this one - can be useful for assessing the "reading age" of long content (more than 150 words). However, they're not great at - testing short UI content that might only contain two or three words. Use them with caution. Look for a simpler word - whenever you can to improve the readability of your content. - - - -#### Be inclusive of people and devices - -- Avoid _click, tap, touch_ instructions as not every device supports touch. -- Instead, use _select_ to instruct a user to interact. -- Avoid relying on directional or color-based cues — _to the right, the blue button_. These are problematic for responsive products or users who see colors differently. -- Instead, write _the main menu_ or _select "Apply changes"_. Name the component or area you’re referencing. - -#### Write as if the user is in a rush - -- Avoid repetition and padding. -- Phrases we use when writing formally or presenting — _please note, so, in fact, in other words_ — should be cut. -- Chunk content and use headings to help the user find what they need. - -#### Be direct and straightforward - -- Lead with the reason (why), by front-loading messages with words that address the user’s needs. -- Leave the user with a clear instruction of how to address that need. -- Avoid relying on Twilio or industry jargon, idioms, or cultural references to communicate what you mean. -- Use the words that are most familiar to the user. - -#### It’s ok to bend grammatical rules to sound natural - -- End sentences with prepositions — _of, with, for_ — if it sounds less awkward. -- And you can start sentences with _But_ or _And_. -- Use contractions with pronouns — _it’s, there’s, you’ll, we’ll, you’re_ — to sound conversational. - - - Exception: avoid contractions in error messages - - Avoid contractions in negative scenarios. When a user is stressed, their comprehension suffers. Often users will - read can’t as can, missing the -’t at the end. Write out error messages or destructive action - warnings in full. - - - -## Punctuation - -#### Ampersands & - -**Avoid using ampersands.** In exceptional circumstances, if space is unavoidably restricted or it's part of a product/brand name, use "&". - -**Do** use "and" instead of an ampersand (&). - -- _Voice and messaging_ -- _Create and submit a Regulatory Bundle._ -- _Messages sent from AT&T to Twilio numbers are not impacted._ - -**Don't** use "&" just to make content shorter. If space is an issue, address the content and design together. +**Write for the reading level of a 10-13 year old.** Use simple, short sentences and common words. Explain technical terms. - Why? + Using readability tools - Using "and" rather than the ampersand symbol (&) supports localization and users with lower literacy or cognitive - impairments. Some screen readers can’t interpret the code behind an ampersand, which obscures the meaning for the - user. + Readability tools can be useful for assessing the "reading age" of long content (more than 150 words), but they can be less helpful for short UI content. Look for a simpler word whenever you can to improve the readability of your content. ---- - -#### Apostrophes ' - -**Do** use an apostrophe to indicate possession or belonging. - -- The APIs of Twilio > Twilio's APIs - - _The phone number's prefix._ - - _Choose from one of SendGrid's responsive email designs._ - -**Do** use an apostrophe to indicate missing letters. - -- You are > you're - - _You're not logged in._ - -**Don't** use apostrophes to make a plural. We should never see _Upgrade to buy phone number's_, _Install plugin's_, or _SID's_. - ---- - -#### Commas , - -**Do** use the serial or 'Oxford' comma in a list of 3 or more items. - -- _You can customize the agent desktop, channels, interaction routing, and reporting._ - ---- - -#### Exclamation marks ! - -**Do** use a single exclamation mark to support a celebration. But never more than one at a time (!!) - -- _Congratulations, you sent your first email!_ - -**Don't** use exclamation marks to draw attention to or emphasise an error message or alert. -Exclamation marks can increase anxiety or sound like shouting. Unless it's a clear moment of success, don't use them. - ---- - -#### Hyphens and dashes - – — - -**Do** use hyphens (-) to create compound words. - -- Hyphens never have a space either side. - - _Add-on feature_ - -**Do** use en-dashes (–) indicate a range of values (time, dates, numerical amounts.) - -- En-dashes never have a space either side. - - _0-50 agents_ - - Tip: If your system does not support en-dashes, use a hyphen to indicate range. - -**Avoid** using em-dashes (—) to create an emphatic pause. - -- Tip: It's ok to write a very short sentence to emphasise its meaning. - We might use em-dashes with friends and colleagues in email and chat to signify an added thought, but the user needs clarity over what's important. - Give the thought a sentence or restructure your syntax. - ---- - -#### Parentheses ( ) - -**Do** use parentheses to provide an example or explanation. - -- _Password must contain a special character (&, @, %, \$, ^)_ - -**Do** use parentheses to note an acronym the first time a user encounters it. - -- _Transport Layer Security (TLS) is a mechanism for securing your SIP connections._ - - In this example, the user is familiar with the term "SIP" but not "TLS." - ---- - -#### Periods . - -**Do** end every full sentence with a period. - -- _Enable Flex Dialpad in Console._ -- _Sign up for a free account._ - -**Don't** use periods at the end of fragments or incomplete sentences. +**Be inclusive of devices.** Avoid instructing users to “click,” “tap,” or “touch” things in the UI. Tell them to “select” something instead. -**Don't** use periods at the end of an anchor link if it is the last line on an alert or notification. +**Be inclusive of people.** Avoid relying on directional or color-based cues, like “to the right” or “the blue button.” Instead, name the component you’re referencing. For example “Select **Apply changes.**” ---- +**It’s OK to bend grammatical rules to sound natural.** For example, end sentences with prepositions or start a sentence with “But” or “And” if it sounds less awkward. Use contractions with pronouns — it’s, there’s, you’ll, we’ll, you’re — to sound conversational. -#### Quotation marks " " +## Style standards -**Do** use quotation marks to pick out words from a component or a file name. +These style standards largely mirror the [Twilio style guide](https://library.twilio.com/guidelines/guide/1b8c14a4-287d-47a4-8ac6-1621bfe97a6d/page/34720f98-b7f8-4436-8e66-4f814801eec1), and provide product content-specific examples and rationale, where appropriate. -- _Select "Apply changes"_ -- _We recommend using dedicated accounts for your development environments, like "Flex Production" and "Flex Development."_ +### Abbreviations +Use common abbreviations if space is limited, like in form labels. -**Do** put punctuation inside quotation marks, if necessary. +In general, avoid abbreviations in body copy because it can lead to increased cognitive load and reduce comprehension. An exception to this rule is shortening “information” to “info,” as it is common. -- _To create a new project, select "Create My Flex Project."_ +### Acronyms -**Don't** use quotation marks to refer to products or features. -Products and features are proper nouns and should be capitalized to differentiate them. +Spell out the acronym the first time it is referred to, and then put the acronym in parentheses. ---- +### American English -#### Semicolons ; - -**Avoid** using semicolons. In formal writing, semicolons are useful. In product content, they can be messy and confusing. - -- If you feel your sentence needs a semicolon, simplify it or create two sentences. - -**Do** use punctuation and conjunctions (_and_, _but_, _so_) to separate thoughts. - -- List complex items that already contain a comma using bullet points. For example, state capitals - - _Montgomery, Alabama_ - - _Juneau, Alaska_ - - _Phoenix, Arizona_ - ---- - -## Grammar and formatting - -#### Abbreviations - -**Do** use common abbreviations if space is limited, such as in form headings. - -- _Ref._ in place of _Reference_ -- _No._ or _#_ in place of _number_ -- _Info_ in place of _information_ - -**Do** use a period at the end of the abbreviation if the last letter is not the same as the full word's last letter. - -- _Ref._ in place of reference -- _Info_ in place of information - -_Avoid_ using abbreviations in body copy. It might reduce the character count but it can increase cognitive load and reduce comprehension. - ---- - -#### Acronyms - -**Do** write the phrase in full, followed by the acronym in parentheses the first time a user encounters it. - -- _Transport Layer Security (TLS) is a mechanism for securing your SIP connections._ - - In this example, the user is familiar with the term "SIP" but not "TLS." - ---- - -#### American English - -**Do** use American English spellings throughout products. - -- _Behavior, dialed, color, artifact, center, license_ (for both verb and noun), _-ize_ endings, _program_ (for all meanings) - ---- - -#### Bold and italics - -##### Bold - -**Do** use bold type sparingly, to draw attention to the most important word, number, or short phrase in your copy. - -- Bold type can help a user scan the page more effectively by making landmarks more prominent. - -**Do** consider using bold type to refer to UI elements in instructional content. E.g. - -- _Select the location from **Region/State**._ -- _Select **Continue** to review your order._ - -**Don't** use bold multiple times in body copy or for a whole sentence/paragraph. It dilutes its effect. - -- Only **bold the most important information the user needs to retain** and only use it if user testing indicates a need. -- Consider if putting an important sentence on a new line will do a better job of making it stand out than making it bold. - -##### Italics - -**Avoid** using italic type wherever possible in product content. - -- If you need to draw attention to a word, use bold type. -- If you need to quote a phrase, use quotation marks "like this." -- While you may see italics used elsewhere at Twilio, in products let's keep it simple and avoid it. - ---- - -#### Capitalization - -**Do** capitalize proper nouns – products, people, places. - -- Products include features, programs, or systems that Twilio has given a specific name to. -- If a brand or product name uses a mix of upper and lower case (TwiML, eBay) use the name's convention. -- People are named individuals or identifiable roles. - -**Don't** capitalize general terms (_email, contact center, platform, phone number_) - -- Tip: If it's something Twilio has created or owns, it takes a capital. - ---- - -#### Dates - -**Do** write dates so that they are easy to scan and sound human to read aloud. - -- _Day, Month DD, YYYY_ (_Sunday, May 17, 2020_) — when referencing a specific day and the year is not clear from the context. -- _Month DD, YYYY_ (_May 17, 2020_) — when the day of the week is unimportant or does not help the user scan. -- _Month YYYY_ (_May 2020_) — when only the month is relevant. Useful in subheads to organize chronological lists. - -**Avoid** repeating information. If a history or log organizes its contents using _Month YYYY_ sub-headings, the following line items should use _Day DD_. - -- For the subhead _January 2020_, the dates that follow would read _Wednesday 15_, _Tuesday 28_ and so on. - -**Do** indicate a date range by using _to_ between values. - -- \_January 24 to February 3, 2020 -- _January 24 to 28_ - -**Do** abbreviate months to their first 3 letters if space is limited. - -- _Jan, Feb, Mar_ - -- Tip: If it's absolutely necessary to cite a specific date numerically, use the [ISO 8601 date format](https://www.w3.org/TR/NOTE-datetime#:~:text=Introduction-,The%20International%20Standard%20for%20the%20representation%20of%20dates%20and%20times,Representation%20of%20dates%20and%20times%22.) YYYY-MM-DD But note that this may not be useful to your user. Always consider which format is quickest to scan and easiest to read aloud. - ---- - -#### I/You/We/Us - -**Do** refer to the user as _you_ and to Twilio as _we_. - -- Tip: If the user has agency or ownership, use ‘I’ or ‘my’. - - _If you still can’t connect, contact our support team._ - - _To access billing information, select My Account._ - - _I understand._ (This usage is almost exclusively for legal consent.) - - - Legal content - - Legal content follows different rules to product — e.g., in Terms of Service, Twilio is usually referenced in - the third person. Always check with the legal team if the content regards consent. - - +Use American English spelling. -**Do** say _we_ instead of _Twilio_ +### Ampersands -- It's us talking, so there's no need to refer to us in the third person. -- If "Twilio" is included in a product or feature name, that's ok as that's using it as a noun. +Avoid using ampersands unless space is highly restricted or is part of a product/brand name. ---- +Using “and” instead of an ampersand (&) helps localization and users with lower literacy or cognitive impairments. Also, some screen readers can’t interpret the code behind an ampersand. -#### Lists (all) +### Bold -**Do** start each list item with the same part of speech – usually a noun or verb – to make the list "parallel." +Use bold type sparingly, to draw attention to the most important information the user needs to retain, and only if user testing indicates a need. -- Punctuate the end of each item with a period if it is a complete sentence. -- Be consistent within the list. If one item takes a full point, all items should. +Bold UI elements when instructing the reader to interact with them. For example, “To review your order, select **Continue**.” -**Don't** punctuate the end of an item in a vertical list with a comma or ellipsis "..." +### Capitalization -#### Lists (bullet points) +Capitalize proper nouns, including Twilio products. Before you capitalize, ask “Has Twilio branded this product as something it owns?” If the answer is no, you’re probably incorrectly capitalizing a generic term that’s commonly used in the industry, but not owned by one particular entity. -**Do** use bulleted lists for items linked by a topic. Make the list topic clear in the sentence or heading that precedes it. +If another brand or product name uses a mix of upper and lower case (for example, eBay), use their formatting. -#### Lists (numbered) +### Commas -**Do** use numbered lists for items to be done or understood in a sequence. +Use the serial or 'Oxford' comma in a list of 3 or more items. -**Avoid** listing more than 7 items — it's a lot to take in. Break a big lists into smaller ones with explanatory headings. +### Dates -#### Lists (sentence) +Write dates so that they are easy to scan and sound human to read aloud. -**Do** use a sentence list if you’re explaining a short process, noting up to four options, or highlighting up to four key points. You just read a sentence list. +- Use Day, Month DD, YYYY (Sunday, May 17, 2020) when referencing a specific day and the year is not clear from the context. +- Use Month DD, YYYY (May 17, 2020) when the day of the week is unimportant or does not help the user scan. +- Use Month YYYY (May 2020) when only the month is relevant. -- Sentence lists should be used for no more than four items. Over four? List with bullet points. -- Use the Oxford comma before the last item in a sentence list. +If it's absolutely necessary to cite a specific date numerically, use the [ISO 8601 date format](https://www.w3.org/TR/NOTE-datetime#:~:text=Introduction-,The%20International%20Standard%20for%20the%20representation%20of%20dates%20and%20times,Representation%20of%20dates%20and%20times%22.) (YYYY-MM-DD), but consider which format is quickest to scan and easiest to read aloud. ---- +Avoid repeating information. For example, if a log organizes its contents using Month YYYY (January 2020) sub-headings, the line items should only list the day (Wednesday 15). -#### Numbers +Use a hyphen to indicate a date range. -**Do** use precise numbers to express statistics, metrics, or quantities. Avoid rounding up or down when the user is depending on the information to be accurate. +Abbreviate months to their first 3 letters if space is limited. -**Do** use numerals (1, 2, 3, 45, 101) instead of spelling out the number. +### Exclamation marks -- Percentages _49%_ +Use a single exclamation mark to support a celebration. Never use more than one at a time. -**Do** write expressions that use ordinal numbers in words. +Avoid using an exclamation mark to draw attention to an error message or alert. Exclamation marks can increase anxiety or be interpreted as shouting. -- _One to watch, thousands of options_ -- _First, create a profile_ +### Hyphens and dashes -**Do** use both words and numerals to represent numbers over 1000, unless the user needs a specific number. +Use hyphens to create compound words, like “add-on”. Do not add a space on either side. -- _Up to 40k emails_ -- _More than $1.5B_ -- **Note** this is most commonly used in marketing content — make sure you're giving the user what they need to complete a task, and not overloading them with extra info. +Use en-dashes to indicate a range of values like time, dates, and numerical amounts. Do not add a space on either side. -**Do** use a space between the number and its unit of measurement or its order of magnitude if this is written out in words. +To create an en-dash: +- Mac: Option + - (hyphen) +- PC: Alt + 0150 -- _40 GB, 564 customers_ -- _More than $1.3 billion, 45 million customers_ +Avoid using em-dashes in product copy. They are generally used to offset related information or highlight a break in a sentence. Instead, use short sentences. -**Do** use commas in numbers that are four or more digits. +### I/You/We/Our -- _1,365 messages sent_ +- Speak directly to the user and address them as “you”. +- Refer to Twilio as “we” instead of “Twilio”, unless there is confusion about who “we” would refer to. +- It’s OK to use the possessive “our” when referring to Twilio. +- It’s OK to use “Twilio” as a noun when referring to the product, or as required by legal. +- Reserve using “I” for legal content (for example “I understand”). -**Don't** use commas in error codes, account numbers, or phone numbers. +### Italics ---- +Avoid using italic type wherever possible in product content. +- To draw attention to a word, bold it. +- If you need to quote a phrase, use quotation marks. -#### Sentence case +### Lists -**Do** use sentence case everywhere, even in H1s, CTAs, and navigation. Sentence case makes content feel more human and it's generally easier to scan. +Start each list item with the same part of speech to make the list “parallel.” -- This is sentence case. (Use this.) -- This is Title Case. (Rarely use this, and only if directed.) -- THIS IS ALL CAPS. (Don’t use this.) +Use periods at the end of each list item only when it’s a full sentence. ---- +Avoid lists of more than 7 items in the product — it's a lot to take in. Break up big lists into smaller ones with explanatory headings. -#### Time +Lists contained within sentences can be hard to digest in product content. Consider using bullets to improve scannability. -**Do** write times so that they are easy to scan and sound human to read aloud. Usually, this means using the 12hr clock, with am/pm modifiers. +### Numbers -- _12:25am_ -- _3:32pm_ +Use precise numbers to express statistics, metrics, or quantities. ---- +Use numerals in most cases (sometimes it just looks wrong!). They’re often easier to comprehend in product and require fewer characters. -## Common errors +Write out ordinal numbers. For example, “third” instead of “3rd.” -#### e.g./i.e. +Use commas in values greater than 999. -- _e.g._ = for example - - _Create a memorable name for your Flex Project, e.g. "Flex Training 2020."_ -- _i.e._ = that is - - Tip: _i.e._ usually precedes a simpler way of saying something. Say it simply the first time. Avoid writing _i.e._ if you can. +Use both words and numerals for numbers over 1,000. For example, “SendGrid sent over 40K emails.” ---- +Use a space between the number and its unit of measurement. For example, “40 GB” or “More than $1.3 billion.” -#### Every day/everyday +Be consistent, even if it means overriding the general rule. For example, “This article has 16 pages, another has 7 pages, and a third has only 5 pages.” -- _Every day_ = each day - - _Twilio supports thousands of customers every day._ -- _Everyday_ = ordinary/usual - - _Twilio supports everyday customer needs, like call routing._ +### Parentheses ---- +Use parentheses to provide an example, explanation, or to note an [acronym](#acronyms). Do not use parentheses for whole sentences. -#### It's/its +### Periods -- _It's_ = contraction of "it"+"is" - - _It's now possible to view real-time queue stats._ - - Tip: Can you say _it is_ instead of the word you want? Does the sentence make sense? You want _it's_. -- _Its_ = possessive pronoun (belonging to it) - - _The company and its customers._ +End every full sentence with a period. ---- +Don't use periods in headings. -#### Log in/login +Don't use periods at the end of fragments or incomplete sentences. -- _Log in_ = verb - - _To access your account, please log in._ -- _Login_ = noun/adjective - - _Enter your login details._ +Don't use periods at the end of an anchor link if it is the last line of a piece of content. ---- +### Quotation marks -#### Set up/setup +Use quotation marks to pick out words from a component or a file name. -- _Set up_ = verb - - _Set up your profile._ -- _Setup_ = noun/adjective - - _System setup information can be found in the user guide._ +Place commas and periods inside the quotation marks. ---- +Don't use quotation marks to refer to products or features. -#### Sign up/sign-up +### Semicolons -- _Sign up_ = verb - - _Sign up for a free account._ -- Sign-up = noun/adjective - - _Visit the sign-up page for more information._ +Avoid using semicolons. They’re too formal for product content. Use two sentences instead. Or simplify the sentence. ---- +### Sentence case -#### Their/there/they're +Use sentence case everywhere, even in H1s, CTAs, and navigation. It feels more human, and is easier to read. -- _Their_ = plural and/or gender neutral possessive pronoun (belonging to them) - - _The main priority for agents is reducing their wrap-up time._ -- _There_ = adverb meaning existing in/at that place - - _There is a new version available._ -- _They're_ = contraction of "they"+"are" - - _Users are important. They're our top priority._ +### Time ---- +Use the “hour:minute” format. For example, “4:15. Use the 12-hour clock with a.m./p.m. modifiers. When necessary, add the time zone after the time. -#### Who/that +### Underlines -- _Who_ = refers to people - - _Team leads who manage multiple business areas can use queues to assign tasks._ -- _That_ = refers to things - - _Companies that require security should enable Secure Media._ +Reserve for links. To draw attention to very important information the user needs to retain, use [bold](#bold) instead. diff --git a/packages/paste-website/src/pages/foundations/content/voice-and-tone/index.mdx b/packages/paste-website/src/pages/foundations/content/voice-and-tone/index.mdx index 096aab5ae5..f4edfc1fae 100644 --- a/packages/paste-website/src/pages/foundations/content/voice-and-tone/index.mdx +++ b/packages/paste-website/src/pages/foundations/content/voice-and-tone/index.mdx @@ -38,187 +38,73 @@ export const getStaticProps = async () => { -## What are voice and tone? +How to use the Twilio voice and tonal qualities to communicate in our products. -#### Voice is the foundation of every written or spoken communication. +## The difference between voice and tone -Voice makes us — Twilio — identifiable, consistent, and familiar. +**Voice** is the foundation of every written or spoken communication. Think of it as Twilio’s “identity.” -#### Tone is how you modify what you say to convey emotion or intent. +**Tone** modifies the voice to be appropriate for the situation. This usually means different words, punctuation, or syntax. -Tone enables you to choose words, structures, punctuation, or syntax appropriate to the scenario. +It’s the difference between how you’d speak to your best friend versus how you’d speak in a job interview. It’s always your voice — you sound the same — but you’d use a different tone. - - Voice or tone? - - Think of your best friend. You can recognize their voice — that doesn't change. But how they speak in a job - interview is different from how they chat with you at the weekend. They sound the same — - that’s voice. But they change how they express themselves — that’s tone. - - +## The Twilio voice ---- +Here are the Twilio voice tenets, as defined by the [Twilio brand team](https://library.twilio.com/guidelines/guide/1b8c14a4-287d-47a4-8ac6-1621bfe97a6d/page/107efbc5-d9d8-40fe-88ee-d6366ed16ede). -### Twilio voice and tone +1. **Conversational**. We write how we speak, and that makes us approachable and relatable. +2. **Thoughtful**. We want our readers to feel like they belong, so our messages to them should always be cultured and intelligent. That’s why we write with a specific person or group in mind. +3. **Reliable**. Twilions are smart, tenacious, accurate and authentic. We know the ins and outs of the products and topics we’re writing about and we speak truthfully about those subjects. +4. **Quirky**. It’s possible to be professional, smart, grounded, easy to understand and fun all at the same time. -#### The Twilio Voice is how we sound in writing or out loud. +How do these voice tenets translate to product content? -The characteristics of our voice don’t change. Twilio always sounds +**Conversational: Write like you’re talking to someone** +- Use common words in simple, short structures. +- Avoid jargon and explain technical terms. -- Human -- Accurate -- Authentic +**Thoughtful: Write for the person using the product** ---- - -#### Tone has four parts - -The four qualities of tone are as follows. The exact mix changes to meet the user’s needs and situation. - -- Positive -- Conversational -- Encouraging -- Knowledgeable - -#### Human = write with the user in mind - -Users succeed when they achieve their goal efficiently and have a positive experience. -Create content that appeals to both their head and heart — content that you'd want to read. - -- Reduce cognitive load by using common words in simple, short structures. -- Be empathetic and consider the user's situation and emotional state. +Users succeed when they achieve their goal efficiently and have a positive experience. Create content that meets our users where they’re at. +- Consider the user's situation and emotional state. - Offer appropriate reactions, just as you would face-to-face. -#### Accurate = write with precision - -Users need our content to be accurate. -They rely on the words we use to help them achieve their goal. -A user should never be surprised by what content means. +**Reliable: Write with precision and transparency** +Users need our content to be accurate and honest. They rely on our products to do what we say they will, and they rely on the words to help them achieve their goals. - Use consistent language for features and products. -- Give the user all the information they need to make a decision. -- Remember, you are not the user. - -#### Authentic = write transparently - -Users need our content to be truthful and evidence-based. -They rely on our products to do what they say. -Being evasive or exaggerating isn’t useful and impacts the user’s trust in our products. - -- Be clear about what is and isn’t possible, particularly with beta or pilot features. -- Never suggest or claim that the product does something it can’t deliver. -- Test the product rigorously so you can be confident and precise about its functions. - ---- - -## Tone - -Tone is used to modify how we communicate, according to the scenario and the user’s situation. -Think of tone as a stabilizer tool. - -We want our users to feel - -- Confident -- At ease -- Empowered -- Reassured - -To do that, we use a combination of tonal qualities - -- Positive -- Conversational -- Encouraging -- Knowledgeable - ---- - -### Tonal qualities - -#### Positive - -You're task-focused but warm. When the user wins, you recognize their success genuinely. - -- **Do** be engaging, efficient, and forward-looking. -- **Do** front-load messages with the reason (why) then the action (how.) - - _To get started, add a user_ - - _Congratulations, you sent your first campaign email!_ - -Being over-enthusiastic all the time can sound insincere. Choose moments of infrequent success. - -- **Don't** be annoying, hyperbolic, or misleading. -- **Don't** add empty phrases or punctuation to try to sound positive. - - _First up, add a user, then we can get going!_ - -#### Conversational - -Speak to the user as you would in person. Imagine you're on friendly, but professional terms. - -- **Do** be friendly, approachable, and straightforward. -- **Do** use common contractions (you’ll, we’re, let’s.) - - _You're not logged in_ - -You aren't jokey or casual with the user. Remember, the user has a goal to complete. - -- **Don't** be colloquial or over-familiar. -- **Don't** use slang or idioms. These can exclude users and obscure meaning. - - _Head over to Studio_ - - _Oops, looks like you're a few characters short of a password_ - -Write as much copy as you need to convey the message in a conversational tone. - -- **Avoid** sounding robotic or sacrificing meaning to save space. Shorter is not always better or clearer. -- **Avoid** prioritizing space or design over comprehension or conversational language. - - _Create_ -- Instead, choose the words that clearly communicate what an interaction does. - - _Create Agent profile_ - -#### Encouraging - -Show empathy, advise, and guide. Show the user how to succeed to give them confidence. - -- **Do** be helpful, reassuring, and supportive. -- **Do** include a _please_ if the user is making additional effort. - - _To apply changes, please reload the page_ - - _Change an Agent's skill level in Agent Profile_ - -Users need support and reassurance without judgement. +- Give the user the info they need to make a decision. +- Be clear about what is and isn’t possible. +- Never suggest or claim that the product does something it can’t. -- **Don't** be patronizing or sound impatient. -- **Don't** precede an instruction with _just_ or frame it as being easy or simple. - - _To apply changes, just reload the page_ - - _Change an Agent's skill level easily in Agent Profile_ +**Quirky: Add a little character** -#### Knowledgeable +Users spend a lot of time using our products. When it makes sense, have a bit of fun. -Empower the user by sharing information. Show them the edges of the flow for context. +## The Twilio tone spectrum -- **Do** be informative, guiding, and clear. -- **Do** signpost what’s next to enable discovery. - - _To see available networks, select a country_ +According to the Twilio brand team, [our tone spectrum](https://library.twilio.com/guidelines/guide/1b8c14a4-287d-47a4-8ac6-1621bfe97a6d/page/107efbc5-d9d8-40fe-88ee-d6366ed16ede) ranges across: -Avoid surprising the user with another step and don't assume they know as much as you. +- Direct +- Balanced +- Casual -- **Don't** be dictatorial, superior, or know-it-all. -- **Don't** make the user guess what an interaction will do. - - _Select country_ +When deciding which of these tones to adopt, consider the user, the place in their experience, what they need, and their emotional state. In other words, put yourself in their shoes. ---- +Here are some examples of when you might use each of these tones for in-product experiences: -## Finding tone that works +### Direct -Identify the user, their place in the experience, what they need, and their emotional state. Put yourself in their shoes. +- **Encountering an error**: This is likely a negative experience for the user, and they’re not looking for humor or chumminess. Instead, they’re likely expecting straightforward information about how to fix the problem. +- **Accepting legal terms**: This is a serious experience for the user. The user is likely looking for professional, clear information about the terms they’re about to accept. -| Interaction | Context | User need | Approach | -| :---------- | :----------------------------------------------------------------------------- | :------------------------------------------------------------------------ | :----------------------------------------------------------------------- | -| Neutral | A repeated interaction (Login screen, confirmation message) | Familiarity and recognition. Efficiency, nothing unusual, and no friction | Conversational and positive. Be efficient, approachable, and unobtrusive | -| Positive | A high point (Completion of a complex flow, first-time success with a process) | Confirmation of success. A positive affirmation and clear next step | Positive and encouraging. Be congratulatory and forward-looking | -| Negative | An error or problem (Access denied, system failure) | Resolution and reassurance. A clear solution and reassurance | Knowledgeable and encouraging. Be clear, informative, and calm | +### Balanced -Tone balances the interaction, leaving the user in a net-positive place emotionally. +**Onboarding to a new feature**: This is an experience that requires a largely instructive tone. The user wants to learn about how they can benefit from using the new feature, and we want them to feel confident doing so! A dash of motivation could be appropriate. -If in doubt, aim to sound like a friendly specialist. Be the voice of someone you'd want to come back to for support or guidance. +### Casual +- **First completion of a large or difficult task**: The user is probably feeling happy and relieved to have made it through the task - a bit of celebration is warranted! -Every interaction deserves consideration. If you can write in the Twilio Voice and use appropriate tonal qualities, your content will have a strong, user-focused foundation.