12 KiB
12 KiB
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 |