Style Guide

Writing standards for tripplan.ing documentation.

Page types

Choose one type before writing a page:

Guide page

For getting started, tutorials, and walkthroughs.

Sections: Title → Prerequisites → Step 1: Verb-noun (explanation + command + expected output) → Step 2 → What's next (contextual links)

Concept page

For explaining how things work.

Sections: Title → What this is (2-3 sentences) → How it works (subsections with code from codebase) → Key design decisions → Related pages

Task page (organizer)

For feature documentation that combines admin and attendee perspectives.

Sections: Title → Quick outcome (2-3 sentences) → Setup (admin configuration) → Day-to-day management (admin operations) → Attendee experience (what guests see) → Troubleshooting (symptom/fix table) → Next steps

Reference page

For lookup tables, schemas, and inventories.

Sections: Title → What this covers → Reference (tables, schemas, types) → Examples (if applicable) → Related pages

Writing rules

Structure

• Every page must have an # H1 title
• Use ## H2 for major sections, ### H3 for subsections
• No deeper than ### H3 — if you need ####, restructure
• Keep pages between 80-250 lines (below 80 = too thin, above 250 = consider splitting)

Content

• Lead with what the reader can do, not what the system is
• Use tables for structured information (routes, fields, symptoms)
• Include code snippets from the actual codebase, not hypothetical examples
• Cross-link related pages in a "Related pages" or "Next steps" section

Tone

• Second person ("you") for instructions
• Present tense ("the server starts" not "the server will start")
• Imperative mood for steps ("Configure the domain" not "You should configure the domain")
• No filler ("Note that", "It's important to", "Please")

Terminology

Use these terms consistently:

Term	Not
event	site, app, project
attendee	user, guest, visitor
organizer	admin, operator, owner
platform operator	super admin, root user
add-on	expense, charge, fee
pricing tier	attendee type, category
event slug	event name, event key

Code blocks

• Use language hints: typescript`, bash, ````toml
• Keep snippets focused — show the relevant 5-15 lines, not entire files
• Use comments to highlight the important parts
• For CLI commands, show the command and (when useful) expected output

Tables

• Use tables for structured comparisons, field lists, and route maps
• Keep cells concise — single line preferred
• Use | alignment for readability in source

Cross-links

• Link to specific pages, not sections: [Routes & APIs](/reference/routes) not [see above](#routes)
• Use descriptive link text: [Environment Variables](/reference/environment) not [click here](/reference/environment)
• Every page should link to at least one related page

Sidebar organization

Each top-level section has its own contextual sidebar (configured in .vitepress/config.ts):

Path prefix	Sidebar	Pages
/guide/	Getting Started	3 pages
/organizer/	Organizer Guide	13 pages
/deploy/	Deployment	6 pages
/develop/	Developer Guide	7 pages
/reference/	Reference	7 pages

Navigating to a page in a section shows only that section's sidebar.

Related pages

• Monorepo Layout — where docs live in the repo
• Commands — docs build and check commands