Skip to content

STYLE_GUIDE.md

Latest commit

 

History

History
426 lines (292 loc) · 14.1 KB

STYLE_GUIDE.md

File metadata and controls

426 lines (292 loc) · 14.1 KB
Raw

Documentation Style Guide

Version: 2.1
Owner: Documentation Team
Last updated: January 2024
Status: Active — adopted across 4 product lines

This guide defines the standards for all customer-facing and developer-facing documentation. It applies to API references, user guides, quickstarts, changelogs, help articles, and in-product copy.

When this guide doesn't cover something, default to the Google Developer Documentation Style Guide.

Contents

  1. Voice and tone
  2. Word choice
  3. Formatting
  4. Code documentation
  5. API reference standards
  6. Headings
  7. Links
  8. Numbers and units
  9. Error messages
  10. Changelog writing
  11. Accessibility
  12. Review checklist

1. Voice and tone

Voice

Our documentation voice is direct, precise, and respectful of the reader's time. We write as a knowledgeable colleague — not a corporate manual, and not a casual chat.

Direct: Lead with the action or answer. Don't bury the point in context.
Precise: Use the exact technical term. Don't hedge with "kind of" or "basically."
Respectful: Trust the reader. Avoid over-explaining obvious things.

Tone

Tone shifts based on document type.

Document type Tone Example
API reference Neutral, factual "Returns the subscription object on success."
Quickstart Encouraging, direct "You're ready to make your first API call."
Error reference Calm, action-oriented "The card was declined. Ask the customer to use a different card."
Changelog Informative, clear "The cancel endpoint now accepts cancel_reason_code."
Help article Warm, clear "Here's how to update your billing information."

What to avoid

  • Filler phrases: "In order to," "please note that," "it is important to note," "feel free to"
  • Vague intensifiers: "very," "quite," "really," "basically"
  • Marketing language in docs: "powerful," "seamless," "robust," "best-in-class"
  • Passive voice when active is clearer. "The API returns an error" not "An error is returned."
  • Future tense when present works. "The endpoint returns" not "The endpoint will return."

2. Word choice

Preferred terms

Use these terms consistently. Do not substitute synonyms — terminology inconsistency is a major source of developer confusion.

Use this Not this Notes
subscription membership, account, license Unless the product explicitly calls it something else
customer user, client, account In billing context; "user" is acceptable for account/app context
invoice bill, receipt, charge Invoices are documents; charges are events
endpoint route, URL, path "Endpoint" is standard API terminology
parameter argument, field, option Use "parameter" for API inputs; "field" for object properties
field attribute, property, key For object properties in response schemas
request body payload, data "Payload" is acceptable in webhook context
return respond with, send back "The endpoint returns a subscription object"
null nil, None, undefined Use the JSON term in cross-language docs
boolean bool, flag, toggle Spell it out
string str, text, value Spell it out
integer int, number Use "integer" for whole numbers, "number" for floats
Unix timestamp epoch, POSIX time Always clarify format on first mention: "Unix timestamp (seconds)"

Capitalization

  • API (all caps) — not "api" or "Api"
  • REST (all caps) — not "Rest"
  • Chargebee — not "chargebee" or "ChargeBee"
  • Webhook (lowercase) — not "WebHook" or "web hook"
  • OpenAPI (camel case) — not "Open API" or "openapi"
  • Markdown — not "markdown" or "MD"
  • Product names follow their official capitalization

Abbreviations

Spell out on first use: "JavaScript (JS)." After first use, abbreviation is fine.

Abbreviations that are always acceptable without expansion: API, URL, HTTP, JSON, YAML, SDK, CLI, UI, ID.

3. Formatting

Bold

Use bold for:

  • UI elements the user interacts with: Settings → API Keys
  • Terms being defined for the first time in a document
  • Critical warnings (in conjunction with a callout)

Do not bold for emphasis. If something is important, say why it's important — don't rely on formatting to carry meaning.

Italics

Use italics for:

  • Titles of external documents: Google Developer Documentation Style Guide
  • Introducing a new term before defining it: Dunning is the process of retrying failed payments.

Inline code

Use inline code for:

  • All code: plan_id, subscription.status, auto_collection: 'on'
  • File names: index.js, .env, openapi.yaml
  • HTTP methods: GET, POST, DELETE
  • Status codes: 200, 404, 429
  • Values: true, false, null
  • Endpoints: /subscriptions/{id}/cancel

When in doubt, code-format it.

Callouts

Use callouts for information the reader must not miss, or that is important but would interrupt flow.

> **Note:** Voided invoices are excluded from revenue reporting.

> ⚠️ **Warning:** Never retry `fraudulent` or `stolen_card` errors.

> 💡 **Tip:** Pass `Idempotency-Key` to safely retry failed requests.

Do not overuse callouts. If everything is important, nothing is.

Tables

Use tables for:

  • Reference data with three or more attributes (error codes, parameters, field definitions)
  • Side-by-side comparisons

Keep table prose short — tables are for scanning. If a cell needs more than two sentences, consider a separate section.

4. Code documentation

Code block language tags

Always specify the language:

```bash
curl https://...
```

```javascript
const result = await chargebee.subscription.create({...});
```

```json
{ "id": "sub_HxKtL3QmVr9p" }
```

Code sample requirements

Every code sample must:

  • Run as written — if it won't execute, it's wrong
  • Use realistic values — no foo, bar, test123. Use sub_HxKtL3QmVr9p, plan_pro_monthly, cus_KmQ9xT4pRw2v
  • Include expected output — show what success looks like
  • Reflect current SDK versions — update when SDK changes

Multilingual samples

For API documentation, provide samples in: Node.js, Python, Ruby, PHP, Go — in that order. If a feature isn't supported in a given SDK, say so explicitly rather than omitting the tab.

Inline comments in code

Comment the why, not the what. Developers can read code.

// ✅ Good — explains non-obvious behavior
const result = await chargebee.subscription.create({
  plan_id: 'pro-monthly',
  customer_id: customer.id,
  auto_collection: 'on',  // Chargebee will charge automatically at renewal
}).request();

// ❌ Bad — restates the code
const result = await chargebee.subscription.create({
  plan_id: 'pro-monthly',  // the plan ID
  customer_id: customer.id,  // the customer ID
}).request();

5. API reference standards

Parameter documentation

Every parameter entry must include:

  • Name — exact name as it appears in the request
  • Type — string, integer, boolean, enum, object, array
  • Required or optional
  • Description — what it does and what it affects, not just what it is
  • Default value if optional
  • Valid values for enums
  • Example value

Field documentation

Every response field entry must include:

  • Name — exact field name
  • Type
  • Nullable? — explicitly state if the field can be null
  • Description — what the value represents
  • Example value

For monetary values, always note the unit: "Amount in smallest currency unit (cents for USD)."
For timestamps, always note the format: "Unix timestamp (seconds)."

Endpoint descriptions

An endpoint description must answer:

  1. What does this endpoint do?
  2. What is created, modified, or returned?
  3. What are the non-obvious side effects? (e.g., "Creating a subscription may generate an invoice.")
  4. What are the constraints? (e.g., "Cannot be called on a cancelled subscription.")

Error documentation

Document every error a developer can realistically encounter — not just generic 400/401/404. See Section 9: Error messages.

6. Headings

Hierarchy

  • H1 — Page or document title. One per page.
  • H2 — Major sections.
  • H3 — Subsections.
  • H4 — Use sparingly. If you need H4, consider restructuring.

Heading style

Sentence case for all headings: "How subscription state transitions work" not "How Subscription State Transitions Work."

Exception: Proper nouns follow their own capitalization: "OpenAPI 3.1 schema reference"

Headings should describe content, not introduce it. "Error codes" not "About error codes" or "Understanding error codes."

Verb form in task-based headings

Use gerunds for process docs: "Creating a subscription," "Handling payment errors"
Use imperatives for steps: "Create a subscription," "Handle the error"

Be consistent within a document — don't mix.

7. Links

Link text

Link text must describe the destination — never "click here," "this page," or "more information."

✅ See [payment gateway errors](./payment-gateway-errors.md) for resolution paths.
❌ For more information, [click here](./payment-gateway-errors.md).

When to link

  • On first mention of a concept with its own documentation
  • At the end of a section under "Related" or "Next steps"
  • In troubleshooting when the fix requires reading another doc

Do not link every mention of a term. Link the first mention per section.

External links

External links open in the same tab (standard web behavior). Do not add target="_blank" without a specific reason.

8. Numbers and units

  • Spell out numbers one through nine. Use numerals for 10 and above.
  • Exception: always use numerals before units — "3 seconds," "5 minutes," "1 hour"
  • Use numerals in code, parameters, and technical specifications
  • Do not start a sentence with a numeral — restructure the sentence

Monetary values:

  • In prose: "$49/month," "$4,900"
  • In code/API context: always state the unit — "4900 cents (USD)"
  • In tables: be consistent — pick a format and use it throughout

Timestamps:

  • Always specify the format on first use in a document: "Unix timestamp (seconds since epoch)"
  • Use ISO 8601 for human-readable dates: 2024-06-18, not June 18, 2024 or 6/18/24

9. Error messages

Error message format

All error messages in documentation must include:

  1. Error identifier — the api_error_code value (code-formatted)
  2. What it means — plain language
  3. Why it happens — the root cause
  4. What to do — the resolution path

Writing resolution paths

Resolution paths are the most important part of error documentation. Write them as actions:

✅ Ask the customer to use a different card.
✅ Retry with exponential backoff.
✅ Verify the API key matches the site name.

❌ This error occurs when the card is declined.
❌ The customer's card was not accepted.

Customer-facing error messages

When documenting customer-facing copy:

  • Write what the customer should do, not what the system did
  • Don't expose internal error codes or technical terms
  • Don't blame the customer
✅ "Your payment couldn't be processed. Please try a different card."
❌ "Error: card_declined (code 3001). Transaction rejected by issuer."

10. Changelog writing

Entry format

Every changelog entry must include:

  • Category — New, Changed, Fixed, Deprecated, Removed, Security
  • Release date
  • Affected endpoints or features
  • What changed — specific and concrete
  • Breaking change indicator if applicable
  • Migration guidance for breaking changes or deprecations
  • Links to relevant API reference and guides

Breaking vs. non-breaking

Always explicitly state when a change is non-breaking: "This is a non-breaking change. No action required."

For breaking changes: state the change, the migration path, and the deadline.

Tense

Changelog entries use past tense for what changed, present tense for what developers need to do:

✅ "The cancel endpoint now accepts `cancel_reason_code`. Update any status checks..."
❌ "We added `cancel_reason_code` to the cancel endpoint."

11. Accessibility

  • All images require alt text that describes the content, not just the subject. "State transition diagram showing subscription moving from active to cancelled" not "diagram"
  • Tables require header rows with <th> elements
  • Code blocks use semantic markup, not plain <pre> blocks
  • Color is never the only means of conveying information — pair color with text labels or icons
  • Heading levels are sequential — don't skip from H2 to H4

12. Review checklist

Before publishing or approving any documentation:

Content

  • All parameters and fields are documented (no stubs or "coming soon")
  • Code samples run as written and output matches documentation
  • Error codes documented with resolution paths
  • Non-obvious side effects are called out
  • Links are valid and point to current content

Style

  • Voice is direct, precise, and consistent with this guide
  • Terminology matches the preferred terms table (Section 2)
  • No filler phrases or marketing language
  • Inline code formatting applied correctly
  • Heading hierarchy is correct (H1 → H2 → H3, no skips)

Technical accuracy

  • Reviewed by a subject matter expert (engineer or PM)
  • API behavior matches current production (not a future state)
  • SDK versions and endpoints are current
  • Deprecation notices include removal dates

This style guide was built by reviewing Google Developer Style Guide, Microsoft Writing Style Guide, Apple Style Guide, and Divio's Documentation System, then adapting for the products at hand.

Questions or proposed changes: open a PR or contact the docs team.