Documentation Standards

Guidelines for creating and maintaining Elite Events documentation.

Purpose

Consistent, high-quality documentation that serves developers, admins, and project managers effectively.

General Principles

1. Clarity First

• Use simple, direct language
• Avoid jargon unless explained
• Include examples for complex concepts

2. Audience Awareness

• Know your reader (developer, admin, PM)
• Adjust technical depth accordingly
• Provide role-specific entry points

3. Maintainability

• Keep docs close to code they describe
• Update docs with code changes
• Use templates for consistency

4. Accessibility

• Provide multiple navigation paths
• Include table of contents for long docs
• Link related documentation

Document Structure

File Naming

• Use SCREAMING_SNAKE_CASE.md for top-level docs
• Use kebab-case.md for guides and subdirectories
• Be descriptive: API_REFERENCE.md not API.md

Front Matter

Every document should start with:

# Document Title

Brief description (1-2 sentences).

**Last Updated**: YYYY-MM-DD
**Status**: Draft | In Review | Active | Deprecated
**Audience**: Developers | Admins | Everyone

---

Table of Contents

• Required for docs >200 lines
• Use markdown anchors
• Keep 2-3 levels deep maximum

## Table of Contents

- [Section 1](#section-1)
- [Section 2](#section-2)
  - [Subsection](#subsection)

Content Guidelines

Headings

• Use ATX-style (#) not underline-style
• One H1 per document (title)
• Hierarchical: H1 → H2 → H3
• No skipping levels (H2 → H4)

# Title (H1)
## Main Section (H2)
### Subsection (H3)
#### Detail (H4, use sparingly)

Code Blocks

Always specify language:

```typescript
const example = "code";
```

Include comments for complex code:

```typescript
// Fetch user from database
const user = await prisma.user.findUnique({
  where: { id: userId }  // Safe from SQL injection
});
```

Examples

• Provide complete, runnable examples
• Include expected output
• Show both success and error cases

### Example: Create User

**Request:**
```bash
POST /api/users
```

**Response (Success):**
```json
{
  "id": 1,
  "name": "John Doe"
}
```

**Response (Error):**
```json
{
  "error": "Email already exists"
}
```

Links

• Use relative links within docs: [Guide](guides/DEVELOPMENT.md)
• Use descriptive link text: [API Reference](API_REFERENCE.md) not [Click here](API_REFERENCE.md)
• Check links aren't broken

Lists

• Use - for unordered lists (consistent with project)
• Use 1. for ordered lists (auto-numbering)
• Indent sub-items with 2 spaces

- Item 1
  - Sub-item 1.1
  - Sub-item 1.2
- Item 2

1. Step one
2. Step two
   - Note about step two
3. Step three

Tables

• Use for structured data
• Keep columns reasonably sized
• Include headers

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data     | Data     | Data     |

Emojis

• Use sparingly for visual markers
• Consistent meanings:
  • ✅ Complete / Success
  • ❌ Error / Failed
  • 📋 Pending / TODO
  • 🚀 Quick Start / Launch
  • ⚠️ Warning
  • 💡 Tip / Insight

Document Types

Guide (e.g., DEVELOPMENT.md)

# Guide Title

Brief overview of what this guide covers.

## Prerequisites
- Required knowledge
- Required setup

## Topics
### Topic 1
Explanation + examples

### Topic 2
Explanation + examples

## Next Steps
- Where to go from here

Reference (e.g., API_REFERENCE.md)

# Reference Title

## Resource Name

### Endpoint

METHOD /path

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|

**Response:**
```json
{...}

Errors:

• 400: Description

### Tutorial (e.g., QUICKSTART.md)
```markdown
# Tutorial Title

What you'll accomplish in X minutes.

## Step 1: Title
Instructions

command

## Step 2: Title
Instructions

## Verify
How to check it worked

Plan (e.g., PLAN_X.md)

# Plan X: Title

## Overview
Goals and scope

## Phases
### Phase 1: Title
- Tasks
- Deliverables

## Success Criteria
How we measure completion

## Timeline
Estimated duration

Style Guide

Voice

• Active voice: "Run the command" not "The command should be run"
• Second person: "You can configure..." not "One can configure..."
• Present tense: "The function returns..." not "The function will return..."

Formatting

• Bold for UI elements: Click Save
• Italics for emphasis (use sparingly)
• Code for inline code, file names, commands
• Use — (em dash) or – (en dash) appropriately

Capitalization

• Sentence case for headings: "Getting started" not "Getting Started"
• Exception: Proper nouns and acronyms (Next.js, API, MySQL)

Numbers

• Spell out one through nine
• Use numerals for 10 and above
• Exception: Technical values always use numerals (5 minutes, 3 files)

Code Examples

Quality Standards

• Tested: Examples should actually work
• Complete: Include all necessary imports/setup
• Realistic: Use realistic variable names and scenarios
• Commented: Explain non-obvious parts

Good Example

// Good: Complete, tested, realistic
import { prisma } from '@/lib/prisma';

async function getUserOrders(userId: number) {
  // Fetch orders with related product data
  const orders = await prisma.order.findMany({
    where: { userId },
    include: {
      items: {
        include: { product: true }  // Include product details
      }
    }
  });

  return orders;
}

Bad Example

// Bad: Incomplete, untested, unclear
async function getStuff(id) {
  const data = await db.query("SELECT * FROM table WHERE id = " + id);
  return data;
}

Maintenance

When to Update

• Immediately: When code changes break docs
• Same PR: Feature docs with feature code
• Weekly: Status updates (STATUS.md)
• Per Release: CHANGELOG.md
• Monthly: Review guides for accuracy

Update Checklist

• Update "Last Updated" date
• Verify code examples still work
• Check links aren't broken
• Update cross-references
• Add CHANGELOG entry (if needed)
• Update INDEX.md (if new file)

Deprecation

When deprecating docs:

1. Add warning at top:

   > ⚠️ **DEPRECATED**: This document is outdated. See [New Doc](NEW_DOC.md) instead.
   

2. Move to archive (optional)

3. Update links pointing to it

4. Update INDEX.md

Templates

Use templates in docs/templates/ for consistency:

• guide-template.md - For new guides
• plan-template.md - For development plans
• issue-template.md - For issue documentation
• api-endpoint-template.md - For API docs

Review Process

Self-Review

Before submitting:

• Spell check
• Grammar check
• Test all code examples
• Verify all links work
• Check formatting renders correctly
• Ensure TOC is accurate

Peer Review

Request review for:

• New major documentation
• Significant updates
• Technical accuracy concerns
• Audience appropriateness

Accessibility

Writing

• Use clear, simple language
• Define acronyms on first use: "API (Application Programming Interface)"
• Provide alternative text for images (when used)
• Use descriptive link text

Structure

• Logical heading hierarchy
• Meaningful section titles
• Consistent navigation
• Multiple entry points

Anti-Patterns

Don't

• ❌ Write documentation after the fact
• ❌ Assume reader knowledge
• ❌ Use ambiguous pronouns ("it", "this")
• ❌ Leave TODOs in published docs
• ❌ Copy-paste without adapting
• ❌ Use screenshots for code (use text)
• ❌ Write "obviously" or "simply"

Do

• ✅ Document as you code
• ✅ Explain prerequisites
• ✅ Be specific and clear
• ✅ Complete before publishing
• ✅ Customize for context
• ✅ Use code blocks for code
• ✅ Respect the reader

Metrics

Good Documentation Has

• High usage (referenced frequently)
• Low support burden (answers questions)
• Positive feedback
• Few clarification questions
• Regular updates

Measure

• Track broken link reports
• Monitor clarification questions
• Collect feedback
• Review analytics (if available)

Questions?

• Check INDEX.md for examples
• Review existing docs in /docs
• Ask team for clarification
• Suggest improvements to these standards

Last Updated: November 20, 2024 Status: Active Version: 1.0