Voice
Writing Style
Active voice, plain words, second person — the rules that apply across every Ontopix context.
Production
Active voice, plain words, second person. These rules apply across every Ontopix context.
Spelling — US English
Hoisted to the top because it's the most-consulted answer.
| Prefer | Avoid |
|---|---|
| color | colour |
| customize | customise |
| center | centre |
| organize | organise |
| analyze | analyse |
| behavior | behaviour |
| license | licence (Both noun and verb use 'license' in US English) |
| rasterize | rasterise |
Dates and times
- Date (standard):
YYYY-MM-DD - Date (display): Month DD, YYYY
- Time: 24-hour (alt: 12-hour with AM/PM)
- Timezone: Always specify timezone for global audiences
General rules
1. Use active voice
Active voice is clearer and more direct.
✗ Your request is processed by the system
✓ The system processes your request
2. Be concise
Respect the reader's time.
✗ In order to proceed, you will need to click on the Save button
✓ Click Save
3. Use simple words
Simple words are more accessible.
| Prefer | Avoid |
|---|---|
| use | utilize |
| start | initiate |
| end | terminate |
| help | facilitate |
| get | obtain |
| show | demonstrate |
| buy | purchase |
| need | require |
| about | regarding |
| before | prior to |
4. Avoid jargon unless necessary
Technical terms should be defined on first use.
✗ OKLCH keeps shade steps even
✓ OKLCH (a perceptually uniform color space) keeps shade steps even
When technical terms are needed, define them on first use
5. Use contractions naturally
Contractions read like spoken English; their absence reads stiff.
✗ We are shipping the dashboard tomorrow
✓ We're shipping the dashboard tomorrow
Avoid in formal legal contexts
6. Address the reader as 'you'
Direct address is clearer and more engaging.
✗ Users can configure their settings
✓ You can configure your settings
Formatting
- Headings. sentence case. Only capitalize the first word and proper nouns.
- Lists. Parallel structure. Every item starts with the same part of speech.
- Numbers. Spell out one through nine; use numerals for 10 and above. Numerals always for technical values, table cells, and units (
8 GB,3 pixels). - Punctuation. Oxford comma on. Em dash
—, en dash–, double quotes by default; curly in marketing, straight in code.
Technical writing
| Element | Style |
|---|---|
| Code inline | backticks |
| File paths | backticks, forward slashes |
| Commands | code blocks for multi-line |
| Variables | backticks |
| Urls | full URL in prose, linked text preferred |
Pitfalls
| Wrong | Right | Why |
|---|---|---|
utilize / initiate / terminate | use / start / end | Latinate verbs read formal and slow; the simple verbs say the same thing. |
Users can configure their settings | You can configure your settings | Second person is direct; third person hides the reader behind a category. |
In order to proceed, you will need to click on the Save button | Click Save | Three words instead of fourteen — same instruction, no padding. |
Your request is processed by the system | The system processes your request | Active voice names the actor; passive hides it. |
Related
- Voice — personality and archetype that grounds these rules.
- Contexts — channel-specific patterns (UI microcopy, marketing, support).
- Terminology — approved terms and forbidden words.
- Guide → Accessibility — cross-domain accessibility rules referenced here.