---
title: "Documentation"
description: "Documentation standards and guidelines"
keywords: [documentation, docs, writing, standards]
---

# Documentation

Standards and guidelines for writing documentation in TraceRTM.

## Documentation Types

### Code Documentation

- **Docstrings**: Function and class documentation
- **Comments**: Inline code explanations
- **Type hints**: Type information

### User Documentation

- **API Reference**: Endpoint documentation
- **Guides**: How-to guides
- **Examples**: Code examples

### Developer Documentation

- **Architecture**: System design
- **Internals**: Implementation details
- **Contributing**: Contribution guides

## Docstring Standards

### Google Style

```python
def create_item(
    title: str,
    view: str,
    status: str = "draft"
) -> dict:
    """Create a new item.

    Args:
        title: Item title (1-255 characters)
        view: Item view (requirements, test-cases, etc.)
        status: Item status (default: draft)

    Returns:
        Created item dictionary with id, title, view, status

    Raises:
        ValidationError: If title or view is invalid
        DatabaseError: If database operation fails

    Example:
        >>> item = create_item("Test", "requirements")
        >>> item["id"]
        'item_123'
    """
    pass
```

## API Documentation

### Endpoint Documentation

```python
@router.post("/api/v1/items")
async def create_item(request: CreateItemRequest):
    """Create a new item.

    Creates a new item in the specified project. The item will be
    created with status "draft" by default.

    **Request Body:**
    - `title` (string, required): Item title
    - `view` (string, required): Item view
    - `status` (string, optional): Item status

    **Response:**
    - `201 Created`: Item created successfully
    - `400 Bad Request`: Invalid request data
    - `401 Unauthorized`: Authentication required

    **Example:**
    ```json
    {
      "title": "User Authentication",
      "view": "requirements",
      "status": "draft"
    }
    ```
    """
    pass
```

## Writing Guidelines

### Clear and Concise

```markdown
# Good
Create a new item in the project. The item will be created with
status "draft" by default.

# Bad
This function will create a new item in the project that you
specify, and it will have a status that is set to "draft" by
default, unless you specify something else.
```

### Use Examples

```python
# Include examples in documentation
"""
Example:
    >>> from tracertm import TraceRTM
    >>> client = TraceRTM(api_key="rtm_live_abc123...")
    >>> item = client.items.create(title="Test", view="requirements")
    >>> print(item["id"])
    item_123
"""
```

## Documentation Updates

### When to Update

- New features added
- API changes
- Behavior changes
- Bug fixes (if behavior changes)

### What to Update

- API reference
- Code examples
- Guides affected by changes
- Changelog

## Related Documentation

- [Code Comments](./05a-code-comments) - Comment guidelines
- [API Documentation](./05b-api-docs) - API docs generation
