Writing Documentation

A guide to writing clear, professional documentation for this wiki.

Document Structure

Every documentation page should follow this structure:

# Page Title

One-sentence summary of what this page covers.

## Overview / What is X?

Brief context (2-3 paragraphs max). Answer: Why should I care?

## Main Content

Organized into logical sections with clear headings.

## Quick Reference (optional)

Tables, cheat sheets, or TL;DR for scanning.

## Next Steps / Related Links

Where to go from here.

Writing Principles

1. Lead with Value

Bad:

This document explains the authentication system architecture...

Good:

Authenticate users in under 5 minutes using JWT tokens.

2. Be Concise

• One idea per paragraph
• Short sentences (under 20 words)
• Cut filler words: "basically", "actually", "in order to"
• Use active voice: "The API returns..." not "The response is returned by..."

3. Show, Don't Tell

Bad:

The configuration is flexible and supports many options.

Good:

# Crawl every 6 hours instead of daily
schedule: "0 */6 * * *"

4. Write for Scanning

Readers scan before they read. Help them:

• Use descriptive headings (not "Introduction")
• Bold key terms on first use
• Use bullet points for lists of 3+ items
• Add tables for comparisons or reference data

Formatting Guidelines

Headings

# Page Title (only one per page)
## Major Section
### Subsection

Don't skip levels (e.g., # to ###).

Code Blocks

Always specify the language:

```python
def hello():
    return "world"
```

For terminal commands, use bash:

```bash
npm install
npm run dev
```

Tables

Use tables for structured data:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | 20 | Items per page |
| `offset` | integer | 0 | Starting index |

Callouts

Use VitePress containers for important information:

::: tip
Helpful suggestion that improves the experience.
:::

::: info
Additional context or background information.
:::

::: warning
Something that could cause problems if ignored.
:::

::: danger
Critical issue that will break things.
:::

When to use each:

Type	Use For
tip	Best practices, shortcuts, pro tips
info	Background context, "good to know"
warning	Common mistakes, gotchas, deprecations
danger	Breaking changes, security issues, data loss

Visual Hierarchy

Use Diagrams for Architecture

ASCII diagrams work well and are easy to maintain:

┌─────────┐     ┌─────────┐     ┌─────────┐
│ Client  │────▶│ Server  │────▶│ Database│
└─────────┘     └─────────┘     └─────────┘

Use Tables for Comparisons

Approach	Pros	Cons
Option A	Fast, simple	Limited features
Option B	Full-featured	Complex setup

Use Lists for Steps

1. First, do this
2. Then, do that
3. Finally, verify

Professional Touches

1. Include Prerequisites

Always state what readers need before starting:

## Prerequisites

- Node.js 18+
- Docker installed
- GitHub account

2. Show Expected Output

After commands, show what success looks like:

curl http://localhost:8000/health

{"status": "healthy"}

3. Add Troubleshooting

Anticipate common issues:

## Troubleshooting

### "Connection refused" error

The server isn't running. Start it with:

\`\`\`bash
docker-compose up -d
\`\`\`

### "Permission denied" error

The service account doesn't have access. Share the sheet with Editor permissions.

4. Link Related Content

Help readers navigate:

## Next Steps

- [API Reference](/projects/zenlym/api) - Full endpoint documentation
- [Deployment Guide](/projects/zenlym/deployment) - Production setup

5. Keep Content Current

• Add "Last updated" when relevant
• Mark deprecated features clearly
• Remove outdated information (don't just strikethrough)

File Organization

Naming Conventions

/projects/
  project-name/
    index.md          # Overview (required)
    architecture.md   # System design
    api.md           # API reference
    setup.md         # Getting started
    config.md        # Configuration options
    deployment.md    # Production deployment
    troubleshooting.md  # Common issues

Use lowercase, hyphens for spaces. The index.md becomes the main page for that folder.

When to Split Pages

Split into separate pages when:

• Content exceeds 500 lines
• Topics are independently searchable
• Readers need different content at different times

Keep on one page when:

• Content is a natural sequence
• Readers typically need everything together
• Splitting would create pages under 100 lines

Checklist Before Publishing

• [ ] Title clearly states what the page covers
• [ ] First paragraph answers "why should I care?"
• [ ] All code blocks have language specified
• [ ] Commands show expected output
• [ ] Prerequisites listed at the top
• [ ] No broken links
• [ ] Proofread for typos

Examples of Good Documentation

Study these for inspiration:

• Stripe API Docs - Clear, consistent, great examples
• Tailwind CSS - Scannable, practical
• Supabase - Good structure, helpful guides