Documentation Style Guide

The single source of truth for how Mantle documentation is written, structured, and maintained.

---

Structure Rules

Code before prose. Show the pattern first, then explain it. Readers scan for code.

300 lines max per page (excluding code blocks). If a page exceeds this, split it.

One concept per page. Don't combine "EventBridge handlers" with "scheduling" — they're separate pages.

Every page opens with a one-sentence description. No preamble, no context-setting paragraphs.

Every code example must be copy-paste-ready. No ... elision without surrounding context that makes the elision clear. No imports omitted unless the page already showed them.

---

Voice Rules

Imperative mood

✅ Create a handler.
❌ You can create a handler.
❌ To create a handler, you would...

Present tense

✅ `buildValidatedResponse` returns a 200 response.
❌ `buildValidatedResponse` will return a 200 response.

No filler words

Remove on sight: simply, just, basically, actually, in order to, note that, please note, it's worth noting.

No hedge words in reference docs

Reference pages state facts, not possibilities.

✅ Pass `auth: 'bearer'` to require a static bearer token.
❌ You might want to consider passing `auth: 'bearer'` if you need auth.

Active voice

✅ Mantle generates `eventbridge.tf` from your config.
❌ Infrastructure is generated by Mantle from your config.

---

Example Rules

Use real examples from production instances — media-downloader and Lifegames Portal. Not TodoApp, not MyService.

✅ import { getAuth } from "@mantleframework/auth"  // from media-downloader
❌ import { getAuth } from "@mantleframework/auth"  // from TodoApp

Minimal working example first, then variations. Start with the simplest case that actually runs. Add options after.

Good/bad comparisons use this format (Prisma pattern):

✅ Good
[code]

❌ Bad
[code]

Show generated output alongside input when the transformation is the point:

// Input: src/lambdas/api/items/GET.ts
export const handler = api(async ({ context }) => { ... })

# Generated: infra/api-gateway.tf
resource "aws_api_gateway_resource" "items" { ... }

---

Reference Rules

CLI flags — table only, no prose in the table:

Flag	Type	Default	Description
--stage	string	—	Deployment target (dev, staging, prod)
--dry-run	boolean	false	Print changes without applying

Config options — name, type, default, one-line description. Link to guide for explanation:

Option	Type	Default	Description
eventbridge.bus	string	—	Custom event bus name. See EventBridge guide.

API functions — signature, params table, return type, one code example. No more.

Group by concern, not alphabetically. Auth functions together, database functions together (Deno pattern). Alphabetical is for search engines, not humans.

---

Page Templates

Guide page

# [Feature Name]

One-sentence description of what this feature does.

## Final result

[Complete working code example — copy-paste-ready]

## Step 1: [Action]

[Minimal explanation. Code if needed.]

## Step 2: [Action]

[Minimal explanation. Code if needed.]

## Next steps

- [Link to related guide]
- [Link to reference]

Reference page

# [Function/Command Name]

One-sentence description.

## Signature

\`\`\`typescript
functionName(param: Type): ReturnType
\`\`\`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|

## Returns

[One-line description of return value]

## Example

[Single complete example]

Showcase pattern page

# [Pattern Name]

One-sentence description of what problem this pattern solves.

## Pattern

[Complete working code — the full pattern, not a snippet]

## How it works

[3–5 bullet points maximum. No paragraphs.]

## Real-world usage

[Link to actual usage in media-downloader or Lifegames Portal, with file path]

## Variations

[Only if genuinely useful. One variation per subsection.]

---

Enforcement

These rules apply to all documentation in mantle/docs/. When reviewing a PR that touches docs, check:

• [ ] Page opens with one sentence
• [ ] Code appears before its explanation
• [ ] No filler or hedge words
• [ ] All examples are copy-paste-ready
• [ ] Page is under 300 lines (excluding code blocks)