feat(docs): add UX writing content guidelines#860
Draft
heatherbarranco wants to merge 2 commits into
Draft
Conversation
Adds terminology, capitalization & punctuation, voice & tone, inclusive writing, and writing for translation pages. Includes revisions: updated Add/Create/Build/Run/Job definitions, added Add-vs-Create tie-breaker, and Latin abbreviations guidance. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new Content / UX writing section to the Apollo docs site under apps/apollo-docs/app/content, providing guidance pages for terminology, voice/tone, inclusive writing, capitalization/punctuation, and writing for translation.
Changes:
- Adds multiple new MDX pages under
app/content/covering UX writing guidelines. - Adds
app/content/_meta.tsto define sidebar labels and ordering for the new section.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| apps/apollo-docs/app/content/writing-for-translation/page.mdx | New page with translation-focused writing guidelines. |
| apps/apollo-docs/app/content/voice-and-tone/page.mdx | New page defining Apollo voice, tone, and style rules. |
| apps/apollo-docs/app/content/terminology/page.mdx | New terminology definitions + component copy guidance. |
| apps/apollo-docs/app/content/inclusive-writing/page.mdx | New inclusive writing guidance with examples and callouts. |
| apps/apollo-docs/app/content/capitalization-and-punctuation/page.mdx | New capitalization/punctuation rules including Latin abbreviation guidance. |
| apps/apollo-docs/app/content/_meta.ts | Defines the nav labels/order for the new content section. |
|
|
||
| # Writing for translation | ||
|
|
||
| Write content that translates clearly and accurately across languages. Some languages (e.g. German, Finnish) expand text by 20–30%, so short, literal phrasing is essential. |
|
|
||
| **Use:** aren't, can't, couldn't, didn't, doesn't, don't, hasn't, haven't, isn't, it's, let's, shouldn't, that's, there's, they're, they've, wasn't, we'll, we're, weren't, what's, where's, won't, you'll, you're, you've | ||
|
|
||
| **Avoid:** Regional contractions (ain't, y'all, twas) and overly formal alternatives (do not, cannot). |
Comment on lines
+1
to
+7
| export default { | ||
| 'voice-and-tone': 'Voice and tone', | ||
| 'capitalization-and-punctuation': 'Capitalization & punctuation', | ||
| 'inclusive-writing': 'Inclusive writing', | ||
| 'writing-for-translation': 'Writing for translation', | ||
| terminology: 'Terminology', | ||
| }; |
Comment on lines
+1
to
+7
| export default { | ||
| 'voice-and-tone': 'Voice and tone', | ||
| 'capitalization-and-punctuation': 'Capitalization & punctuation', | ||
| 'inclusive-writing': 'Inclusive writing', | ||
| 'writing-for-translation': 'Writing for translation', | ||
| terminology: 'Terminology', | ||
| }; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Scoped from #766 — this PR covers the content/UX writing pages only.
Test plan
🤖 Generated with Claude Code