Color palette

Five primary tokens drive everything. All secondary colors derive from these. Use CSS custom properties consistently so the palette can be updated in one place.

Semantic usage

Typography

Three faces cover every context. Load all three from Google Fonts or self-host for production.

Spacing scale

Base unit is 4px. All layout spacing uses multiples.

Voice principles

These apply to all writing — client docs, the site, blog posts, LinkedIn. They reflect a 40-year philosophy about how documentation actually works.

• Say what you mean, then stop. Every sentence earns its place. If removing it doesn't change the meaning, remove it.
• Specific beats general. "Cut documentation cycles by three weeks" is better than "improved efficiency." Reach for the concrete detail.
• Active voice, present tense. "The script generates a config file" not "A config file is generated by the script."
• Trust the reader. Write for someone competent encountering something new — not for someone who needs hand-holding, and not for someone who already knows everything.
• Show the system. Don't just document individual features. Explain how things fit together. Context is the product.
• No hedging without reason. Avoid "generally," "usually," "in most cases" unless they carry real information. If something is always true, say it is.

Register by context

Vocabulary rules

Use these words

Number rules

• Spell out one through nine; use numerals for 10 and above.
• Always use numerals before units: 3 seconds, 64 MB, 2 requests/second.
• Never start a sentence with a numeral. Rewrite the sentence.
• Use the Oxford comma.

Procedure

Use for any task that requires steps in a specific order. The template below applies to client docs, how-to articles, and setup guides alike.

## [Verb phrase: "Configure the webhook endpoint"]

Brief context sentence. What this accomplishes, and when you'd do it.

**Before you begin:**
- Prerequisite one
- Prerequisite two (omit this section if none)

**Steps:**

1. [Imperative verb phrase.] Expected result if not obvious.

2. [Next step.] Add a code block if the user needs to run something:
   ```bash
   command --flag value
   ```

3. Verify the change by [doing X]. You should see [Y].

**Result:** One sentence. What the user now has or can do.

**Next steps:** (Optional) Link to the related task or reference page.

API endpoint reference

Consistent structure for every endpoint. Readers scan — put the most important information (method, path, what it does) first.

### `POST /v1/integrations/{id}/sync`

Triggers a manual sync for the specified integration.

**Authentication:** Bearer token required  
**Rate limit:** 10 requests per minute per workspace

#### Request

| Field       | Type    | Required | Description                        |
|-------------|---------|----------|------------------------------------|
| `force`     | boolean | No       | Overrides the cooldown period.     |
| `source_id` | string  | Yes      | ID of the source connection.       |

**Example request:**
```http
POST /v1/integrations/int_8x3k/sync
Authorization: Bearer {token}
Content-Type: application/json

{
  "force": false,
  "source_id": "src_4j2m"
}
```

#### Response

Returns a `SyncJob` object on success.

```json
{
  "job_id": "job_9z1p",
  "status": "queued",
  "created_at": "2026-04-19T14:30:00Z"
}
```

#### Error codes

| Code | Meaning                                     |
|------|---------------------------------------------|
| 400  | Invalid or missing `source_id`              |
| 409  | Sync already in progress for this integration |
| 429  | Rate limit exceeded                         |

Release notes

## 2.4.1 — April 19, 2026

### New features
- **Sync scheduling:** Set recurring sync windows per integration from the Settings panel. [See Scheduling syncs →]

### Improvements
- Mapping validation now runs before a sync starts, not after. This catches configuration errors earlier and reduces failed jobs.
- The error reference page now includes a filterable lookup table.

### Bug fixes
- Fixed an issue where the OroCommerce connector dropped custom field values on update. (#1847)
- Corrected rate limit headers that were reporting the wrong reset time.

### Breaking changes

> **Heads up:** The `POST /sync` endpoint now requires `source_id`. Calls that omit it return a 400 error starting in this release. Update any automated scripts before upgrading.

Error reference entry

## ERR-2041: Source connection timeout

**Severity:** Warning  
**Component:** Data sync engine  
**Introduced:** v2.1.0

### What it means

The sync job could not reach the source system within the configured timeout window. The job is paused, not failed — it will retry automatically.

### Common causes

- The source system is temporarily unavailable or under high load.
- A firewall rule is blocking outbound connections on port 443.
- The OAuth token has expired and the connector can't refresh it.

### Resolution

1. Confirm the source system is reachable from your network.
2. Check the connection credentials in **Settings → Integrations**.
3. If the token has expired, re-authenticate from the integration detail page.

If the error persists after re-authentication, contact support with the `job_id` from the error log.

Headings

• Never skip heading levels (H1 → H3 is invalid).
• Don't use headings for decorative emphasis. If the section doesn't need navigation, use bold instead.
• Keep headings short enough to scan in a TOC — ideally under 8 words.

Lists

• Parallel structure within a list. All items start with the same part of speech.
• No nested lists beyond one level. Restructure instead.
• If every bullet is a sentence long, consider whether prose would read better.

Code and commands

• Inline code for: values, filenames, parameters, function names, UI element labels.
• Code blocks for anything the user runs, copies, or pastes. Always include the language identifier.
• In prose, use the exact capitalization of the thing you're naming: "the Config object," not "the config object."
• Never truncate code examples. If an example is too long, split into stages or use a GitHub link.

# Always tag the language
```bash
pip install --break-system-packages requests
```

# Not this
```
pip install --break-system-packages requests
```

Callouts

Four types. Use the one that matches the actual severity.

Tables

• Always include a header row. Headers are bold, sentence case.
• Left-align text columns. Right-align number columns.
• No merged cells — they break accessibility and markdown rendering.
• Aim for 3–5 columns maximum. Beyond that, consider multiple tables or restructure as a list.
• Every column needs a clear, distinct label. "Value" and "Data" are not distinct.

Links

• Link text describes the destination: "See API endpoint reference" not "click here" or "this page."
• For external links in client docs, add "(external link)" when the context might not make it obvious.
• On LinkedIn posts, put the outbound link in the first comment, not the post body.
• Don't link the same destination twice in one section. Link on first mention only.

Reference hierarchy

When a style question isn't answered here, escalate in this order and stop at the first answer:

Voice & tone

The Google guide describes the target as conversational, friendly, and respectful — not pedantic, not overly casual, not pushy. The goal is a knowledgeable colleague talking to a competent peer, not a lecturer or a marketer.

• Conversational, not colloquial. Write closer to spoken English than formal prose, but don't write the way you actually talk. Cut filler, but keep contractions.
• Contractions are encouraged. Use don't, can't, isn't, you're, there's. Negation contractions are especially useful — it's harder to miss "don't" than "do not." Avoid invented contractions like guides're and three-word forms like mightn't've.
• No please in instructions. "Click Save" not "Please click Save." Politeness reads as noise in procedural text.
• Read it aloud. If it sounds unnatural or stilted when spoken, rewrite it. Not every sentence has to be conversational, but awkward sentences usually hide a clearer version underneath.
• Transitions matter. Phrases like "Though" and "This way" connect ideas and reduce choppiness. But don't reach for "However" or "Nonetheless" reflexively — they can make prose more stilted, not less.

Language & grammar

Person and pronouns

Tense

• Present tense for general behavior. "The server sends an acknowledgment." Not "The server will send an acknowledgment."
• Future tense only for genuinely future events. "The file will be archived the next time the backup runs." — future tense is correct here because the archiving happens later.
• Never use future tense for product features. Don't write about how a feature "will work" after an update. Document what exists now; update when the feature ships.
• Avoid hypothetical would. Don't write "This would cause an error." Write "This causes an error."

Voice

Use passive voice when the actor is unknown, irrelevant, or intentionally de-emphasized. In those cases it's fine.

Capitalization

• Sentence case for headings. "Configure the webhook endpoint" not "Configure the Webhook Endpoint."
• Product and feature names. Capitalize exactly as the product owner does. When in doubt, check the product's own UI or documentation.
• UI elements. Capitalize to match the UI label exactly. Bold the element name: click Save, open the Settings menu.
• Don't capitalize "the" before a product name unless it begins a sentence: "Open the Google Cloud console" not "Open the Google Cloud Console" (unless "Console" is the actual product name).
• Acronyms. All caps, no periods: API, URL, JSON, HTML. Spell out on first mention if the audience may not know it.

Spelling

• American English. Use Merriam-Webster as the authority; choose the first listed spelling when alternatives exist.
• One word: filename, codebase, dropdown, checkbox, timestamp, username, workaround, setup (noun), login (noun/adjective).
• Two words or hyphenated: sign in (verb), log in (verb), command line (noun), command-line (adjective).
• Check the GMD word list before the Google guide for any term with a project-specific convention.

Anthropomorphism

Software doesn't know, think, want, or feel. Be precise about what systems actually do.

Formatting rules (Google guide)

Procedures

• Imperative mood. Start each step with an action verb: "Click," "Open," "Run," "Configure."
• State the condition before the action. "If you want to limit results, add a filter parameter." Not "Add a filter parameter if you want to limit results."
• One step, one action. If a step has sub-actions, either make them separate steps or use a sub-list — but avoid sub-lists more than one level deep.
• Include expected results when they're not obvious. "Click Deploy. The status changes to Running within about 30 seconds."

Lists

• Use numbered lists for sequences. Use bulleted lists for non-sequential items.
• Introduce a list with a complete sentence followed by a colon.
• Use parallel structure. If one item starts with a verb, all items start with a verb.
• Use end punctuation on list items only when one or more items form complete sentences. Be consistent: if one gets a period, all get periods.
• Avoid starting a list item with an article (a, an, the) or the word "you" — restructure so items begin with verbs or nouns.

Code in text

• Use code font (inline backticks) for: commands, class names, method names, parameters, property names, element names, file extensions, environment variables, literal strings, and keyboard input the user types.
• Use code font for UI strings that appear verbatim in code — but use bold + sentence case for UI labels the user clicks or selects.
• Use {curly_braces} for placeholder values in code samples. Document each placeholder's meaning.
• Language-tag every code block. No exceptions.

UI elements

Special topics

Timeless documentation

Documentation that references a specific "now" ages instantly. Write to stay accurate across software versions and time.

• Avoid currently, now, at this time, soon, new, latest, modern — these all become inaccurate the moment something changes.
• Don't pre-announce features. Document what ships; update when it changes.
• Avoid above and below for cross-references. Use the section or heading name instead: "See Language and grammar" not "See the section above."

Global audience

• Avoid idioms, proverbs, and culturally specific expressions. Readers whose first language isn't English may not recognize them, and they don't translate well.
• Use unambiguous date formats: April 19, 2026 — not 4/19/26 or 19/4/26.
• Avoid humor, sarcasm, and references that assume shared cultural context.
• Use simple, direct sentence structures. Complex subordinate clauses are harder to parse in a second language.

Inclusive language

• Avoid ableist and loaded terms: crazy, insane, blind spot, cripple, sanity check. Use precise alternatives: unexpected, unclear, limitation, slow down, verification.
• Avoid unnecessarily gendered language. Use "they" for singular generic references.
• Avoid terms with slavery or violence connotations in technical contexts: master/slave, blacklist/whitelist. Use primary/replica, allowlist/blocklist.
• When in doubt, check the Google inclusive language guidelines.

Excessive claims and future features

• Don't make unsupported superlative claims: best, fastest, most powerful, industry-leading. These require proof and create legal risk.
• Don't allude to unreleased features, even obliquely. If a feature is coming, document it when it ships.
• Avoid vague promises: "soon," "in a future release," "we're working on."

How to use this list

Each entry shows the preferred form, any disallowed alternatives, and usage notes. Entries marked Client-specific apply only to the named project — don't carry them into other work.

A–F

G–M

N–Z

Terms to avoid

These terms appear frequently in tech writing but should be replaced with more precise language.