Writing Documentation

Write documentation for the person who must understand or operate the system later. Explain current behavior in plain language, show the relevant source location, and keep procedures where readers will look for them.

Choose The Right Section

Content	Location
Prerequisites, installation, and command lookup	docs/getting-started/
Product behavior and feature overviews	docs/product/
Implementation patterns, models, and packages	docs/development/
Complete endpoint contracts	docs/api-reference/
Local setup, deployment, and operations	docs/infrastructure/
Team process and authoring guidance	docs/team-onboarding/

Link to an existing detailed page instead of copying it. Short contextual repetition is useful when it lets a reader understand the current page without following every link.

What To Include

• State what the feature, component, or procedure does.
• Explain why a decision matters when the reason helps future work.
• Link to exact source paths for implementation details.
• Use small, verified examples rather than exhaustive source inventories.
• Put warnings before destructive or security-sensitive commands.
• Label planned behavior clearly and keep it separate from current behavior.
• Update navigation in docs/.vitepress/config.mjs when adding a discoverable page.

For an API endpoint, document the method, path, authentication, input, output, and important error cases in the relevant API reference. For a component, show representative usage and document the props needed to understand that example; link to source for the complete current type.

Style

Use direct sentences and active voice. Prefer concrete statements:

Better Auth uses Redis as secondary storage.

Avoid vague claims such as "uses industry best practices". Avoid promising capabilities that the source does not implement. Use headings that help a reader scan for a task or concept.

VitePress Examples

Frontmatter

Frontmatter is optional:

---
title: New Feature Guide
description: How to work with the feature
---

Containers

::: tip
Useful context that helps the reader succeed.
:::

::: warning
A condition that can cause failure or unexpected behavior.
:::

::: danger
A command or action that can destroy data or expose credentials.
:::

::: details Advanced details
Optional detail that most readers can skip.
:::

Code Blocks

Use a language tag and include only enough surrounding code to explain the task:

```bash
pnpm run docs:dev
```

```typescript
const event = await eventService.getEventDetails(eventId)
```

Diagrams

Use a diagram when relationships are clearer visually than as prose:

```mermaid
flowchart LR
  Browser --> Cloudflare --> API --> PostgreSQL
```

Keep labels short and explain important constraints in nearby prose.

Preview And Validate

Run from the repository root:

pnpm run docs:dev
pnpm run docs:build

The development server is available at http://localhost:5173. With the full Docker stack running, use https://docs.jubiloop.localhost.

Review Checklist

• [ ] The page describes current behavior or clearly labels planned behavior.
• [ ] Commands, paths, names, and examples match the source.
• [ ] Destructive steps include scope, backup, and recovery guidance.
• [ ] Secrets and private operational data are not exposed.
• [ ] Detailed contracts and procedures are linked instead of duplicated.
• [ ] Links and navigation point to the intended pages.
• [ ] Headings and prose are concise and scannable.
• [ ] pnpm run docs:build passes.