documentation-rules

Documentation Rules — Aiyu Agent Kit

Standards for clear, helpful, and maintainable documentation.

---

🔴 CRITICAL: Documentation Essentials

README.md Requirements

Every project must have a README with:

# Project Name

> One-line description of what this project does

## Features

- Feature 1: Brief description
- Feature 2: Brief description

## Installation

```bash
npm install
# or
pip install -r requirements.txt

Usage

npm start
# or
python main.py

Configuration

Environment variables needed:

• API_KEY — Your API key
• DATABASE_URL — Connection string

License

MIT

### Code Comments

```python
# ✅ GOOD — Explain WHY, not WHAT
# Retry 3 times because external API is occasionally flaky
MAX_RETRIES = 3

# ✅ GOOD — Document complex logic
# Using sliding window approach to maintain O(n) complexity
# instead of naive O(n²) nested loop approach
def find_substring(s: str, pattern: str) -> int:
    ...

# ❌ BAD — Obvious comments
x = x + 1  # Increment x by 1

---

🟡 HIGH: API Documentation

Function/Method Documentation

def create_user(
    email: str,
    password: str,
    role: str = "user"
) -> User:
    """
    Create a new user account.
    
    Args:
        email: User's email address (must be unique)
        password: Plain text password (will be hashed)
        role: User role, defaults to "user"
        
    Returns:
        User object with generated ID
        
    Raises:
        ValidationError: If email format is invalid
        DuplicateError: If email already exists
        
    Example:
        >>> user = create_user("[email protected]", "secure123")
        >>> user.email
        '[email protected]'
    """
    ...

API Endpoint Documentation

## POST /api/users

Create a new user.

### Request

```json
{
  "email": "[email protected]",
  "password": "securepassword",
  "role": "user"
}

Response

201 Created

{
  "id": "usr_123",
  "email": "[email protected]",
  "role": "user",
  "created_at": "2024-01-15T10:30:00Z"
}

400 Bad Request

{
  "error": "Invalid email format",
  "field": "email"
}