Style Guide

Standards for writing documentation in the Loop Platform docs site. Consistent style makes pages easier to scan, reduces review friction, and helps agents generate docs that match human-written pages.

Writing Conventions

Voice and tense

• Active voice. Write “the service validates the token”, not “the token is validated by the service”.
• Present tense. Write “this endpoint returns a list”, not “this endpoint will return a list”.
• Second person. Address the reader as “you” when giving instructions.
• Imperative mood for steps. Write “Run the command”, not “You should run the command”.

Clarity

• Lead with the most important information. Bury caveats in callouts, not in the opening sentence.
• One idea per paragraph. If a paragraph covers two concepts, split it.
• Define acronyms on first use — for example, “PHI (Protected Health Information)”.
• Prefer short sentences. If a sentence has more than one comma, consider splitting it.

Tone

• Be direct and confident, not hedging (“this should work” → “this works”).
• Avoid marketing language. Docs are reference material, not sales copy.
• Skip unnecessary pleasantries (“Let’s go ahead and…” → just state the action).

Code Examples

Language tags

Always include a language tag on fenced code blocks so syntax highlighting works correctly:

```typescript
const result = await client.identity.getMe();
```

Common tags used in this repo: typescript, python, bash, json, sql, yaml.

Completeness

Prefer complete, runnable examples over fragments. A reader should be able to copy-paste and run the example with minimal modification.

Expected output

Include expected output where it helps the reader verify they are on the right track:

curl -s https://api.platform.loop.health/healthz | jq .

{
  "status": "ok",
  "version": "1.4.2"
}

Error responses

Show error responses alongside success responses so the reader knows what to handle:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired access token"
  }
}

Markdown Conventions

Headings

• H1 (#) — page title only. Every page has exactly one H1.
• H2 (##) — major sections.
• H3 (###) — subsections within an H2.
• H4 (####) — use sparingly for deeply nested content.

Do not skip heading levels (e.g., jumping from H2 to H4).

Tables

Use tables for structured data like field/value pairs, configuration options, or comparisons:

Callouts

Use Nextra callouts for information that stands apart from the main flow:

import { Callout } from "nextra/components";
 
<Callout type="info">Informational note — background context.</Callout>
 
<Callout type="warning">
  Warning — something that could cause problems if ignored.
</Callout>
 
<Callout type="error">
  Error — a critical constraint or breaking-change notice.
</Callout>

Lists

• Use unordered lists for items with no sequence.
• Use ordered lists for steps that must be followed in order.
• Keep list items parallel in structure (all start with a verb, or all are noun phrases).

File Naming

Cross-Linking

Internal links

Always use relative paths for internal links:

See the [Onboarding guide](/build/onboarding) for setup instructions.

Link density targets

Where to link

• Link concept terms to their Concepts page on first mention.
• Link CLI commands or tools to their reference page.
• Every “Next Steps” section should have 2–4 links to related pages.

API Documentation

Request/response examples

Every documented route must include a complete example request and response:

curl -X POST https://api.platform.loop.health/identity/v1/users \
  -H "Authorization: Bearer tok_example_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "Jane Doe"
  }'

{
  "id": "usr_xyz789",
  "email": "user@example.com",
  "name": "Jane Doe",
  "created_at": "2026-01-15T10:30:00Z"
}

Authentication headers

Always include the Authorization header in API examples. Use the placeholder tok_example_abc123 for bearer tokens.

Error responses

Show at least one error response per endpoint, typically the most common failure:

curl -X POST https://api.platform.loop.health/identity/v1/users \
  -H "Authorization: Bearer tok_expired_000" \
  -H "Content-Type: application/json" \
  -d '{"email": "invalid"}'

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}

Next Steps

• Onboarding — New engineer ramp-up path.
• Production-Readiness Checklist — What “done” looks like for a service.
• Service Architecture — How services are structured.
• Handle Webhooks — Example of a well-structured guide.