# Writing copy

## Role

You are writing interface copy for Cognite customer-facing applications. Every piece of UX text must be purposeful, concise, conversational, and clear. Always identify the target audience persona before writing — the persona determines reading level, technical vocabulary, and tone.

For code-level accessibility (keyboard navigation, ARIA, focus, headings, live regions), see `handling-states.md`.

## Audience personas

Canonical persona definitions live in the cogdocs repository (`cogdocs/cogdocs-metadata.mdx`, **Audience** section). This summary covers what matters for microcopy decisions.

| Persona | Technical level | UX copy implication |
|---|---|---|
| `businessUser` | Low | Plain language; outcomes over features; domain terms OK, avoid platform jargon |
| `businessDecisionMaker` | Low | Plain language; ROI, business value, strategic impact; minimal technical detail |
| `appMaker` | Mid | Configuration, automation, outcomes; avoid deep code/API detail |
| `dataAnalyst` | Mid | Analytics, insights, dashboards; data terms OK, keep explanations clear |
| `partner` | Mid–high | Precise; balance technical accuracy with clarity |
| `administrator` | High | Technical terms OK; reliability, security, compliance, access; be precise |
| `dataEngineer` | High | Technical terms OK; pipelines, ingestion, transformation |
| `developer` | High | Technical terms OK; APIs, SDKs, integrations; precise and concise |
| `aiEngineer` | High | Technical terms OK; ML/AI, models, automation |
| `dataScientist` | High | Technical terms OK; experiments, models, analytics |
| `securityEngineer` | High | Technical terms OK; IAM, threats, compliance |
| `solutionArchitect` | High | Technical terms OK; integration, strategy, best practices |
| `internal` | Varies | Can use Cognite-internal jargon; match internal conventions |

**Reading level:** Low = 7th–8th grade; Mid = 9th–10th grade; High = 10th–11th grade.

When the persona is unknown, default to plain language and outcomes.

## Voice and tone

Voice is consistent; tone adapts to the user's emotional state.

| Scenario | Tone | Example |
|---|---|---|
| First-time onboarding | Friendly, welcoming | "Let's get started — Cognite Data Fusion is ready when you are." |
| Technical documentation | Clear, direct, supportive | "Configure your endpoint and authenticate using your API key." |
| Error messages | Empathetic, constructive | "Something went wrong. Try refreshing, or check your connection." |
| Success states | Encouraging, concise | "Your data is now flowing." |
| Product tours / help | Conversational, helpful | "Want a quick tour? We'll walk you through the essentials in under 2 minutes." |
| High-stakes actions | Serious, transparent | "Delete pipeline? All history will be permanently removed." |

## Grammar and style

### Language and capitalization

- **American English**: color, center, organization, modeling
- **Sentence case everywhere**: "Create data model" — not "Create Data Model". No exceptions for UI text. Only proper nouns and product names are capitalized: Cognite Data Fusion, OPC-UA, Aura.
- **No all-caps**
- **No "CDF" in UI copy** — customers may white-label the platform; use product or feature names instead

### Numbers and units

- **Numerals for all numbers**, including those under 10: "6 queries", "3 items", "1 result"
- Non-breaking space between number and unit: "50 Mbps"
- Don't use "(s)" or "(es)" — choose singular or plural based on context

### Abbreviations and punctuation

- No Latin abbreviations: use "for example" not "e.g.", "and more" not "etc."
- Define acronyms and technical terms when first used (unless writing for technical personas)
- No ampersands (&): use "and" — including in headings
- **Oxford comma**: "apples, oranges, and pears"
- No exclamation marks in UI copy
- No period after labels, tooltip text, or single-sentence bulleted list items; use periods for multiple/complex sentences
- Ellipsis (…): only for ongoing processes or truncated text — use sparingly

### Pronouns

- Don't mix "my" and "your" in the same context
- **"My [resource]"** for app-owned items: "My data", "My assets"
- Minimize "I" and "we" representing the application; focus on the user's perspective
- Avoid ambiguous pronouns ("this", "that") without an explicit referent — name the thing

## Action labels

Use sentence case with an object: "Edit model", "Delete asset".

### Approved labels

| Label | Use when |
|---|---|
| Add | Taking an existing object into a new context ("Add to canvas") |
| Apply | Setting filtered values that affect subsequent system behavior |
| Approve | User agrees; initiates next step in a business process |
| Back | Returning to the previous step in a sequence or hierarchy |
| Cancel | Stopping the current action or closing a modal — warn of data loss |
| Clear | Clearing all fields/selections; restores defaults |
| Close | Closing a page, panel, or secondary window — often icon-only |
| Copy | Copying an object to the clipboard |
| Create | Making a new object from scratch |
| Delete | Permanently destroying an object |
| Discard | Discarding unsaved changes during create/edit |
| Download | Transferring a file from remote to local |
| Duplicate | Creating a copy in the same location as the original |
| Edit | Changing data/values of an existing object |
| Export | Saving data in an external format; typically opens a dialog |
| Import | Bringing data from an external source; typically opens a dialog |
| Next | Advancing to the next step in a wizard |
| Finish | Completing a multi-step wizard |
| Open | Opening a drawer, modal, or new page within current context |
| Publish | Making content available to intended users |
| Refresh | Reloading a view that is out of sync with the source |
| Register | Creating a new user account |
| Remove | Removing an object from the current context without destroying it |
| Reset | Reverting to last saved or default state |
| Save | Saving pending changes without closing the window/panel |
| Search | Goal-oriented action to find precise information |
| Select | Choosing one or more options from a list |
| Show / Hide | Revealing or removing an element from view without deleting — use as a pair |
| Sign in / Sign out | Entering or exiting the application |
| Undo / Redo | Reversing or re-applying the most recent action |
| Upload | Transferring a file from local to remote |
| View | Presenting additional information or properties for an object |

### Labels to avoid

| Avoid | Use instead | Reason |
|---|---|---|
| Confirm | The specific action verb ("Delete", "Send") | Too vague |
| Log in / Log out | Sign in / Sign out | "Log" is technical jargon |
| Sign up | Register | Avoids confusion with "Sign in" |
| Submit, OK, Yes | The specific outcome verb | Generic; tell users what happens |
| Click here, Read more | Descriptive link text | Inaccessible; not input-agnostic |

## UI text patterns

### Titles
Noun phrases, sentence case. Examples: "Asset overview", "Pipeline runs", "Configure integration"

### Buttons and CTAs
Active imperative verb + object. 2–4 words target, 6 max. Examples: "Save changes", "Delete pipeline", "View details"

### Error messages
Pattern: `[What failed]. [Why/context if known]. [What to do].`
Examples:
- "Ingestion failed. Check your extractor configuration and try again."
- "Couldn't save changes. Connection lost. Reconnect and retry."
Avoid: blame language, dead ends with no recovery path

### Success messages
Past tense, specific, brief. Pattern: `[Action] [result]`
Avoid "successfully"; that's implied in the pattern
Examples: "Changes saved", "Pipeline started", "Integration configured"

### Empty states
Explanation + CTA. Example: "No assets yet. Connect a data source to start exploring."

### Tooltips
One to two sentences, present tense. Pattern: `[What it is]. [What it does or why it matters].`
Examples:
- "Asset ID. The unique identifier for this asset in Cognite Data Fusion."
- "Time granularity. Controls how data points are aggregated in the chart."
Never repeat the label. Never write more than 2 sentences.

### Confirmation dialogs
State the consequence, not just the action. Pattern: `[What will be lost or affected]. [Reversibility]. [Specific action].`
- Primary CTA: match the specific action ("Delete pipeline", not "Confirm")
- Secondary CTA: always provide a clear exit ("Cancel")
Examples:
- "Delete pipeline? All runs and history will be permanently removed. This can't be undone."
- "Remove team member? They'll lose access to all shared resources immediately."
Avoid: "Are you sure?", manipulative phrasing

### Form fields
- **Labels**: Clear noun phrases ("Time series ID", "Email address")
- **Placeholder text**: Use sparingly, only for standard formats like "name@example.com"
- **Helper text**: Verb-first; explain why the information is needed

### Notifications
Verb-first title + contextual description. 10–15 words total.
Example: "Extractor disconnected. Check your network and reconnect."

## Accessibility

- Use **"Select"** not "Click" — input-agnostic: mouse, keyboard, touch, voice
- Avoid ambiguous pronouns — screen readers lose surrounding context
- Write descriptive link text: "Read pricing details" not "Click here"
- Alt text by image type:
  - Icon → describes function: "Download PDF" not "download icon"
  - Link image → describes destination: "Contact support" not "question mark"
  - Chart/diagram → summarizes meaning: "Bar chart showing pipeline throughput declining 20% in Q3"
  - Decorative image → empty alt text (`alt=""`)
  - Never write "image of" or "photo of"
- For charts and metrics, describe key trends or values in adjacent text — don't rely on visual encoding alone
- Target 8–14 words per sentence (8 = 100% comprehension, 14 = 90%)
- Pair visual indicators with text: "Error: field required" alongside a red icon

## Date and time formatting

- **Prefer written dates**: "2 January 2023" not "02/01/2023"
- **Relative vs absolute**: ≤24 h from now → relative ("32 min ago"); >24 h → absolute ("2 Jan 2023")
- Always include the year unless obvious from context
- No ordinal numbers: "2 January" not "2nd January"
- Separate date and time with "at": "2 Jan 2023 at 10:00 AM" — no comma
- **12-hour time**: uppercase AM/PM, no periods, space before: "10:00 AM"
- **Time zone**: UTC only; spell out "UTC" in text-only contexts
- Never make the user convert time zones — handle in code
- Ranges: consistent format across start and end; for ongoing processes use absolute start + "ongoing" until complete
- Duration: no comma between units ("10 minutes 3 seconds"); space between number and unit in running text ("3 min"); no space in controls ("3min")

**Time unit abbreviations** (no periods; same form singular/plural):
ms, s, min, hr, d, wk, mo, yr

**Day abbreviations** (3 chars for i18n):
Mon, Tue, Wed, Thu, Fri, Sat, Sun

**Month abbreviations** (4 chars for i18n):
Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec

## Localization

- Keep sentences short with the subject near the start — compound clauses increase translation cost
- Maintain consistent terminology and capitalization across strings (critical for translation memory)
- No Latin abbreviations in translatable strings: "for example" not "e.g.", "and more" not "etc."
- Avoid idioms and cultural references
- No ampersands: use "and"
- Small words (a, the, that, is): include in prose; may omit only in space-constrained labels and CTAs

## Benchmarks

| Element | Target | Maximum |
|---|---|---|
| Buttons / CTAs | 2–4 words | 6 words |
| Titles | 3–6 words, 40 characters | — |
| Tooltips | 10–20 words | 2 sentences |
| Error messages | 12–18 words | — |
| Instructions | 14 words | 20 words |
| Notifications | 10–15 words total | — |
| Line length | 40–60 characters | 70 characters |