Docs Style Guide

What This Is

This guide defines the canonical writing contract for tripplan.ing documentation. The goal is clean, readable pages with fewer sections and clearer task momentum.

How It Works

Choose one page type before writing.

Task page (default)

Use exactly these sections:

1. ## Quick Outcome
2. ## Do This
3. ## Check + Fix
4. ## Next Move (optional, recommended)

Task page rules:

• Quick Outcome: 2-3 lines in plain language.
• Do This: one numbered flow; put blockers under a short “Before you begin” list at the top if needed.
• Check + Fix: include both Confirm and If it fails bullets.
• Next Move: one best next link, not a list.
• Keep code samples only for critical actions.
• Prefer verbs over nouns in step labels.

Concept page

Use exactly these sections:

1. ## What This Is
2. ## How It Works
3. ## Limits
4. ## Related Tasks

Concept page rules:

• Explain purpose and boundaries, not procedural detail.
• Link to task/reference pages for execution details.

Reference page

Use exactly these sections:

1. ## What This Covers
2. ## Reference
3. ## Examples
4. ## Related Tasks

Reference page rules:

• Prefer compact tables for commands, fields, and routes.
• Keep language exact and source-aligned.
• Avoid runbook-style narrative unless the page is explicitly operational.

Limits

• Canonical docs live in apps/docs/docs/documentation.
• Root docs/*.md remain pointer-only; policy is indexed in docs/README.md.
• Structural conformance is review-driven; CI enforces build/link integrity.
• Use consistent terms: event slug, admin email, deploy target, attendee, organizer.

Related Tasks

• Operator entrypoint: Quickstart
• Setup lifecycle: New Event
• Contract references: Reference Overview
• Ownership and cadence: Docs Ownership