Documentation Updater

Documentation Updater Skill

Purpose

This skill provides systematic guidance for updating all types of project documentation when finalizing feature implementations, ensuring comprehensive, accurate, and well-structured documentation.

When to Use

• After feature implementation and validation are complete
• Need to document implementation details
• Creating or updating user guides
• Updating API documentation
• Adding architecture diagrams
• Documenting configuration changes

Documentation Update Workflow

1. Implementation Documentation

Objective: Document how the feature was implemented for developers and maintainers.

Location: docs/implementation/issue-<number>-<feature-name>.md

Template:

# Implementation: Issue #<number> - <Feature Name>

## Overview
Brief description of what was implemented and why.

## Solution Approach
Detailed explanation of the implementation approach:
- Architecture pattern used (e.g., repository pattern, service layer)
- Key design decisions and rationale
- Trade-offs considered
- Alternative approaches rejected and why

## Architecture

### Component Structure

src/tools/feature/ ├── init.py # Public API exports ├── models.py # Data models (Pydantic) ├── interfaces.py # Abstract interfaces ├── core.py # Business logic ├── repository.py # Data access layer ├── validators.py # Input validation └── exceptions.py # Custom exceptions

### Data Flow
[Describe how data flows through the system]

### Key Components

#### ComponentName
- **Purpose**: [What it does]
- **Responsibilities**: [What it's responsible for]
- **Dependencies**: [What it depends on]

## Implementation Details

### Models
[Document Pydantic models and their fields]

### Business Logic
[Document core algorithms and workflows]

### Data Access
[Document repository methods and database interactions]

### Validation
[Document validation rules and error handling]

## Security Measures
- **Authentication**: [How auth is handled]
- **Authorization**: [Permission checks implemented]
- **Input Validation**: [Validation at entry points]
- **Output Sanitization**: [XSS prevention measures]
- **Data Protection**: [Encryption, secure storage]
- **Secrets Management**: [How secrets are handled]

## Performance Optimizations
- **Caching**: [Caching strategy if applicable]
- **Database**: [Query optimization, indexing]
- **Async Operations**: [Use of async/await]
- **Resource Management**: [Memory, connections]
- **Response Times**: [Measured response times]

## Testing
- **Unit Test Coverage**: [percentage]%
- **Integration Tests**: [what's covered]
- **Security Tests**: [auth, validation, etc.]
- **Performance Tests**: [benchmarks met]
- **Edge Cases**: [scenarios tested]

## Configuration
Environment variables required:
```bash
FEATURE_API_KEY=your_api_key
FEATURE_TIMEOUT=30
FEATURE_DEBUG=false

Dependencies

New dependencies added:

• package-name==version: [reason for dependency]

Breaking Changes

[List any breaking changes or "None"]

Migration Notes

[Steps needed to migrate or "None required"]

Known Issues

• [Issue 1]: [Description and workaround]

Future Enhancements

References

• Original Issue: #
• Pull Request: #
• Related Issues: #
• Design Document: docs/architecture/.md

**Actions**:
1. Create implementation doc using template
2. Fill in all sections thoroughly
3. Add code examples where helpful
4. Include diagrams for complex flows
5. Document all security and performance measures

**Deliverable**: Complete implementation documentation

---

### 2. User-Facing Documentation

**Objective**: Update documentation that end users and developers will read to use the feature.

#### README Updates

**Location**: `README.md`

**Check if updates needed**:
- Does the feature change installation steps?
- Does it add new CLI commands?
- Does it change configuration?
- Does it add new user-facing features?

**Actions**:
1. Read current README
2. Identify sections needing updates
3. Add new sections if needed
4. Update code examples
5. Verify all links work

**Example addition**:
```markdown
## New Feature: <Feature Name>

Description of what the feature does.

### Usage

```bash
# Example command
llm-tool feature-command --option value

Configuration

Add to your config file:

feature:
  enabled: true
  option: value

Example

from llms.feature import FeatureService

service = FeatureService()
result = service.do_something()

#### User Guides

**Location**: `docs/guides/<feature-name>-guide.md`

**Create guide for complex features**:
```markdown
# <Feature Name> User Guide

## Introduction
What is this feature and who is it for?

## Getting Started

### Prerequisites
- Requirement 1
- Requirement 2

### Installation
```bash
pip install required-package

Basic Setup

llm-tool init feature-name

Usage

Basic Example

# Simple example
from llms.feature import Feature

feature = Feature()
result = feature.process(data)

Advanced Usage

Use Case 1:

[Step-by-step instructions]

Use Case 2:

[Step-by-step instructions]

Configuration Options

Troubleshooting

Common Issues

Problem: Error message or issue Solution: How to fix it

Best Practices

• Practice 1
• Practice 2

Examples

Example 1:

Full working example with explanation

Example 2:

Another complete example

FAQ

Q: Question? A: Answer.

References

• API Documentation: [link]
• Implementation: [link]

**Deliverable**: User guides for new features

---

### 3. API Documentation

**Objective**: Document API endpoints and interfaces.

#### REST API Documentation

**Location**: `docs/api/<feature-name>-api.md`

**For REST APIs**:
```markdown
# <Feature Name> API

## Base URL

https://api.example.com/v1

## Authentication
```bash
Authorization: Bearer <token>

Endpoints

GET /feature/resource

Get a resource.

Request:

GET /feature/resource?param=value
Authorization: Bearer <token>

Response (200 OK):

{
  "id": 1,
  "name": "example",
  "value": 123
}

Error Responses:

• 401 Unauthorized: Missing or invalid token
• 404 Not Found: Resource not found

POST /feature/resource

Create a resource.

Request:

POST /feature/resource
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "example",
  "value": 123
}

Response (201 Created):

{
  "id": 1,
  "name": "example",
  "value": 123,
  "created_at": "2024-01-01T00:00:00Z"
}

Rate Limiting

• Rate limit: 100 requests per minute
• Header: X-RateLimit-Remaining

Error Codes

#### Python API Documentation

**Update docstrings** to be comprehensive:
```python
def create_feature(
    name: str,
    value: int,
    options: Optional[Dict[str, Any]] = None
) -> Feature:
    """
    Create a new feature resource.

    This function creates a feature with the given name and value,
    applying optional configuration if provided.

    Args:
        name: The feature name (1-100 characters, alphanumeric)
        value: The feature value (must be non-negative)
        options: Optional configuration dict with keys:
            - timeout (int): Request timeout in seconds (default: 30)
            - retry (bool): Whether to retry on failure (default: True)

    Returns:
        Feature: Created feature instance with:
            - id: Auto-generated unique identifier
            - name: The provided name
            - value: The provided value
            - created_at: Timestamp of creation

    Raises:
        ValueError: If name is empty or value is negative
        ValidationError: If options are invalid
        APIError: If API request fails

    Examples:
        Basic usage:
        >>> feature = create_feature("example", 123)
        >>> print(feature.id)
        1

        With options:
        >>> feature = create_feature(
        ...     "example",
        ...     123,
        ...     options={"timeout": 60, "retry": False}
        ... )

    Note:
        Feature names must be unique within the system.
        The function performs input validation before API calls.

    See Also:
        - get_feature(): Retrieve existing feature
        - update_feature(): Modify existing feature
        - delete_feature(): Remove feature
    """
    pass

Deliverable: Complete API documentation

4. Architecture Documentation

Objective: Document architectural decisions and system design.

Location: docs/architecture/<feature-name>-architecture.md

When needed:

• Complex features with multiple components
• New architectural patterns introduced
• Significant design decisions made

Template:

# Architecture: <Feature Name>

## Context
Why was this architecture needed?

## Architecture Overview

### System Diagram

┌─────────────┐ │ Client │ └──────┬──────┘ │ ┌──────▼──────────┐ │ API Layer │ └──────┬──────────┘ │ ┌──────▼──────────┐ │ Service Layer │ └──────┬──────────┘ │ ┌──────▼──────────┐ │ Repository │ └──────┬──────────┘ │ ┌──────▼──────────┐ │ Data Store │ └─────────────────┘

### Components

#### API Layer
- **Responsibility**: Handle HTTP requests/responses
- **Technology**: FastAPI/Flask
- **Key Files**: `api/endpoints.py`

#### Service Layer
- **Responsibility**: Business logic
- **Technology**: Pure Python
- **Key Files**: `core.py`

#### Repository Layer
- **Responsibility**: Data access
- **Technology**: SQLAlchemy/File System
- **Key Files**: `repository.py`

## Design Decisions

### Decision 1: <Decision>
**Context**: [Why this decision was needed]
**Options Considered**:
1. Option A: [Description] - Rejected because [reason]
2. Option B: [Description] - **Selected** because [reason]

**Consequences**:
- Positive: [benefit]
- Negative: [trade-off]

### Decision 2: <Decision>
[Same format]

## Data Flow

### Create Flow

1. Client sends POST request with data
2. API layer validates request format
3. Service layer validates business rules
4. Repository persists data
5. Response returned to client

### Read Flow
[Describe]

## Security Architecture
- Authentication: [mechanism]
- Authorization: [RBAC, ABAC, etc.]
- Data Protection: [encryption, etc.]

## Performance Considerations
- Caching: [strategy]
- Scaling: [horizontal/vertical]
- Bottlenecks: [identified and mitigated]

## Integration Points
- System A: [how it integrates]
- System B: [how it integrates]

## Future Considerations
- Scalability: [how to scale]
- Evolution: [how to extend]

Deliverable: Architecture documentation with diagrams

5. Configuration Documentation

Objective: Document all configuration options and environment variables.

Update these files:

• README.md: Configuration section
• docs/guides/configuration.md: Detailed config guide
• .env.example: Example environment file

Example .env.example update:

# Feature Name Configuration
FEATURE_API_KEY=your_api_key_here
FEATURE_TIMEOUT=30  # Request timeout in seconds
FEATURE_CACHE_TTL=3600  # Cache time-to-live in seconds
FEATURE_DEBUG=false  # Enable debug logging
FEATURE_MAX_RETRIES=3  # Maximum retry attempts

Configuration guide:

## Configuration Options

### Required Settings

#### FEATURE_API_KEY
- **Type**: string
- **Required**: Yes
- **Description**: API key for authentication
- **Example**: `sk_live_xxxxxxxxxxxx`
- **Where to get**: [URL to get API key]

### Optional Settings

#### FEATURE_TIMEOUT
- **Type**: integer
- **Required**: No
- **Default**: 30
- **Description**: Request timeout in seconds
- **Valid range**: 1-300

## Configuration Methods

### Environment Variables
```bash
export FEATURE_API_KEY=your_key

Config File

# config.yaml
feature:
  api_key: your_key
  timeout: 30

Programmatic

from llms.feature import configure

configure(api_key="your_key", timeout=30)

**Deliverable**: Complete configuration documentation

---

### 6. TECH-STACK Updates

**Objective**: Document new dependencies added.

**Location**: `TECH-STACK.md`

**Add entries for new dependencies**:
```markdown
### <Feature Name> (Added: YYYY-MM-DD)

**Dependencies**:
- **package-name** (version): [Description of why needed]
  - Purpose: [What it's used for]
  - License: [MIT, Apache, etc.]
  - Alternatives considered: [Other options]

**Security Considerations**:
- Vulnerability scan: [Clean/Issues found]
- Maintenance status: [Active/Inactive]

Deliverable: Updated TECH-STACK.md

Documentation Checklist

Use this checklist to ensure comprehensive documentation:

Implementation Documentation

• Implementation doc created in docs/implementation/
• Solution approach documented
• Architecture and components described
• Security measures documented
• Performance optimizations noted
• Testing coverage detailed
• Configuration requirements listed
• Dependencies documented
• Breaking changes noted
• Migration notes provided (if applicable)

User Documentation

• README.md updated (if applicable)
• User guide created (for complex features)
• Usage examples provided
• Configuration options documented
• Troubleshooting section added
• All code examples tested and working

API Documentation

• API endpoints documented (if REST API)
• Request/response formats shown
• Error codes documented
• Authentication documented
• Rate limiting noted
• Python API docstrings complete

Architecture Documentation

• Architecture doc created (if complex feature)
• System diagrams included
• Design decisions documented
• Data flows described
• Integration points noted

Configuration Documentation

• .env.example updated
• Configuration guide updated
• All options documented with types/defaults
• Configuration methods shown

Technical Documentation

• TECH-STACK.md updated (if dependencies added)
• Dependencies documented with rationale
• Security considerations noted

Quality Checks

• All links tested and working
• Code examples tested
• Markdown properly formatted
• No spelling/grammar errors
• Version numbers consistent
• Screenshots current (if applicable)

Best Practices

Writing Style

• Use clear, concise language
• Write in present tense
• Use active voice
• Avoid jargon where possible
• Define technical terms on first use

Code Examples

• Test all code examples
• Use realistic, meaningful examples
• Include imports and setup
• Show expected output
• Handle errors in examples

Organization

• Follow logical structure
• Use consistent heading levels
• Group related content
• Cross-reference related docs
• Maintain table of contents for long docs

Maintenance

• Date all documentation
• Note version numbers
• Link to issues/PRs
• Mark deprecated features
• Update on changes

Common Documentation Patterns

Feature Introduction

## <Feature Name>

<One-line description>

### Overview
<Paragraph explaining what it does and why it's useful>

### Quick Start
<Minimal example to get started>

### Learn More
- [User Guide](link)
- [API Documentation](link)
- [Examples](link)

Code Example Pattern

### Example: <Scenario>

<Brief description of what this example demonstrates>

```python
# Import required modules
from llms.feature import Feature

# Initialize
feature = Feature(option="value")

# Use the feature
result = feature.process(data)

# Handle result
print(result)

Output:

Expected output here

Explanation:

### Troubleshooting Pattern
```markdown
### Common Issues

#### Issue: <Error message or problem>

**Symptoms**:
- What the user sees
- Error messages

**Cause**:
Why this happens

**Solution**:
1. Step to fix
2. Another step
3. Verify it's fixed

**Prevention**:
How to avoid this issue

Supporting Resources

Reference materials for documentation:

• Markdown Guide: https://www.markdownguide.org/
• Google Developer Documentation Style Guide
• Write the Docs: https://www.writethedocs.org/

Integration with Deployment Flow

Input: Completed, validated feature implementation Process: Systematic documentation of all aspects Output: Comprehensive documentation across all types Next Step: Changelog generation

Example Workflow

# 1. Create implementation documentation
Write docs/implementation/issue-123-user-auth.md

# 2. Update README if needed
Edit README.md to add authentication section

# 3. Create user guide for complex feature
Write docs/guides/authentication-guide.md

# 4. Update API documentation
Edit docs/api/authentication-api.md

# 5. Document architecture if complex
Write docs/architecture/auth-architecture.md

# 6. Update configuration docs
Edit .env.example to add AUTH_* variables
Edit docs/guides/configuration.md

# 7. Update TECH-STACK.md if dependencies added
Edit TECH-STACK.md to add new auth libraries

# 8. Verify all links work
Check all cross-references and external links

# 9. Test all code examples
Run each code example to ensure they work

# 10. Review checklist
Ensure all items checked off

Quality Standards

Documentation is complete when:

• All checklist items verified
• Code examples tested and working
• Links verified
• Markdown properly formatted
• Spelling/grammar checked
• Version numbers consistent
• Cross-references complete
• User perspective considered

Source: matteocervelli/llms — distributed by TomeVault.