Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: updates to foundational content pages #3872

Merged
merged 10 commits into from
May 20, 2024
Original file line number Diff line number Diff line change
Expand Up @@ -38,60 +38,35 @@ export const getStaticProps = async () => {

<content>

## 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.

<Callout variant="neutral" marginY="space70">
<CalloutHeading as="h4">Need support with non-product content?</CalloutHeading>
<CalloutText>
{' '}
Visit the <Anchor href="https://www.twilio.com/brand/guidelines/writing-style">
Brand Writing Style Guidelines here
</Anchor>.
</CalloutText>
</Callout>

</content>
</contentwrapper>
49 changes: 13 additions & 36 deletions packages/paste-website/src/pages/foundations/content/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -39,58 +39,35 @@ export const getStaticProps = async () => {

<content>

**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 &mdash; 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 &mdash; the more specific, the better.
- Edge cases or exceptions &mdash; send over screen shots and queries.
- Additional examples &mdash; have a great example of before/after?
- Questions and queries &mdash; if something isn't clear, let us know.

<Callout variant="neutral" marginY="space70">
<CalloutHeading as="h3">Need support with non-product content?</CalloutHeading>
<CalloutHeading as="h3">Got feedback?</CalloutHeading>
<CalloutText>
{' '}
Visit the <Anchor href="https://www.twilio.com/brand/guidelines/writing-style">
Brand Writing Style Guidelines here
</Anchor>.
</CalloutText>
Post to <Anchor href="https://github.com/twilio-labs/paste/discussions">Paste Github discussions</Anchor>{" "} with any usability feedback, edge cases or exceptions, additional examples, or questions.
</CalloutText>

</Callout>

</content>
Expand Down
Loading
Loading