Writing Documentation

This guide explains how to write and maintain documentation for the Jubiloop project.

Documentation Philosophy

Our documentation should enable developers to:

1. Understand any specific component without reading everything
2. Bridge the gap between "I need to work on X" and "I can modify the code"
3. Quickly refresh their memory on patterns and conventions

Documentation Structure

docs/
├── product/              # Product vision and roadmap
├── features/             # Feature-centric documentation
│   ├── authentication/   # Auth overview, backend, frontend
│   ├── organizations/    # Multi-tenant workspaces
│   └── ...              # Other features
├── api-reference/        # API endpoint documentation
├── architecture/         # System design and philosophy
├── backend/             # Backend technical guides
├── frontend/            # Frontend technical guides
├── infrastructure/      # Infrastructure and DevOps
│   └── deployment/      # CI/CD and environments
├── product/             # Product features and data models
│   └── data-models/     # Database schema
├── getting-started/     # Setup and installation
├── packages/            # Shared package documentation
└── team-onboarding/     # Team processes and guides

When to Write Documentation

Write documentation when:

• Adding a new feature or component
• Changing existing patterns or conventions
• Discovering something non-obvious
• Answering the same question multiple times
• Onboarding process

Documentation Standards

1. Context Over Exhaustiveness

Each documentation page should provide:

• What: Brief description of the component/feature
• Why: The reasoning behind decisions
• Where: Code locations and file structure
• How: Patterns and conventions to follow
• When: When to use/not use this approach

2. Code Location Hints

Always include where to find the relevant code:

## Authentication Flow

The authentication system is implemented in:

- `apps/server/app/middleware/auth.ts` - Authentication middleware
- `apps/webapp/src/hooks/use-auth.ts` - Frontend auth hook
- `apps/server/app/controllers/AuthController.ts` - Auth endpoints

3. Practical Examples

Show real examples from the codebase:

## Adding a New API Endpoint

1. Create controller in `apps/server/app/controllers/`:
   ```typescript
   // Example from EventsController.ts
   export default class EventsController {
     public async index({ response }: HttpContext) {
       const events = await Event.all()
       return response.json(events)
     }
   }
   ```

2. Add route in apps/server/start/routes.ts:

   router.get('/events', [EventsController, 'index'])

### 4. Cross-References

Link related documentation:

```markdown
## Database Migrations

For migration basics, see [Database Setup](../backend/database.md).

If you're adding a new model, also check:
- [Data Models](../product/data-models/overview.md) for naming conventions
- [AdonisJS Commands](../backend/cli.md) for CLI usage

Writing Style Guide

Be Direct and Practical

❌ Don't: "The authentication system has been designed with security in mind, utilizing industry best practices..."

✅ Do: "Authentication uses JWT tokens stored in HTTP-only cookies. Tokens expire after 24 hours."

Use Active Voice

❌ Don't: "Environment variables are managed by the env.deploy.yml file"

✅ Do: "env.deploy.yml manages all environment variables"

Include the "Why"

❌ Don't: "We use Cloudflare Pages for frontend hosting"

✅ Do: "We use Cloudflare Pages because it offers unlimited free sites, allowing us to create separate projects per environment without extra cost"

Show Don't Tell

❌ Don't: "Add your environment variable to the configuration file"

✅ Do:

# In env.deploy.yml
DEV:
  server:
    MY_NEW_VAR: 'value' # This becomes DEV_SERVER_MY_NEW_VAR in GitHub Secrets

Documentation Tools

VitePress Features

We use VitePress for documentation. Key features:

Custom Containers

::: tip
Useful tips and best practices
:::

::: warning
Important warnings or gotchas
:::

::: danger
Critical security or data loss warnings
:::

::: details Click to expand
Hidden content for advanced topics
:::

Code Highlighting

```typescript // TypeScript with syntax highlighting const example = "highlighted" ```

```bash

Shell commands

npm run dev ```

Mermaid Diagrams

Adding New Documentation

1. Create the File

# Create new doc in appropriate section
touch docs/backend/new-feature.md

2. Add Front Matter (Optional)

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

3. Update Navigation

Edit docs/.vitepress/config.mjs:

// For feature documentation
{
  text: 'Features',
  items: [
    {
      text: 'New Feature',
      items: [
        { text: 'Overview', link: '/product/features/new-feature/overview' },
        { text: 'Backend Implementation', link: '/product/features/new-feature/backend' },
        { text: 'Frontend Implementation', link: '/product/features/new-feature/frontend' }
      ]
    }
  ]
}

// For technical guides
{
  text: 'Backend Technical Guides',
  items: [
    // ... existing items
    { text: 'New Guide', link: '/backend/new-guide' }
  ]
}

4. Test Locally

npm run docs:dev
# Visit http://localhost:5173

Documentation Checklist

Before submitting documentation:

• [ ] Provides enough context for the specific area
• [ ] Includes code locations and examples
• [ ] Links to related documentation
• [ ] Uses clear, direct language
• [ ] Explains the "why" behind decisions
• [ ] Tested locally with VitePress
• [ ] Navigation updated if new page
• [ ] No typos or broken links

Common Patterns

Environment Variables

When documenting environment variables:

1. Show where to add them in env.deploy.yml
2. Explain the naming convention
3. Show where they're used in code
4. Note any validation or format requirements

API Endpoints

When documenting API endpoints:

1. Show the route definition
2. Include request/response examples
3. List required middleware
4. Note any authentication requirements
5. Link to the controller implementation

Frontend Components

When documenting frontend components:

1. Show basic usage example
2. List all props with types
3. Include common patterns
4. Note any performance considerations
5. Link to the component file

Maintenance

Regular Reviews

• Review documentation regularly
• Update docs when changing code
• Remove outdated information
• Add missing context based on questions

Documentation Debt

Track documentation needs in Shortcut with the documentation label. Common needs:

• Missing "how-to" guides
• Outdated examples
• Unclear explanations
• Missing cross-references

Getting Help

• Review existing docs for examples
• Use VitePress documentation for syntax help
• Check with your teammate for guidance