Documentation Management Guide¶

This guide explains how to manage and organize the intent-kit documentation using the built-in CRUD system.

Overview¶

The documentation is organized into logical sections:

Core Concepts - Fundamental concepts and architecture
API Reference - Complete API documentation
Configuration - Configuration and setup guides
Examples - Working examples and tutorials
Development - Development and testing guides

Management Script¶

Use the scripts/manage_docs.py script to manage documentation:

# List all documentation files
python scripts/manage_docs.py list

# List files in a specific section
python scripts/manage_docs.py list --section concepts

# Create a new file
python scripts/manage_docs.py create \
  --section api \
  --filename new_api.md \
  --title "New API" \
  --description "Documentation for new API"

# Update file metadata
python scripts/manage_docs.py update \
  --section api \
  --filename new_api.md \
  --status complete

# Move a file
python scripts/manage_docs.py move \
  --section examples \
  --filename old_example.md \
  --new-section concepts \
  --new-filename new_concept.md

# Delete a file
python scripts/manage_docs.py delete \
  --section examples \
  --filename old_example.md

# Generate status report
python scripts/manage_docs.py report

# Validate file structure
python scripts/manage_docs.py validate

File Status¶

Each documentation file has a status:

pending - File exists but needs content
complete - File is fully documented

File Structure¶

Each documentation file should follow this structure:

# Title

Brief description of the content.

## Overview

Detailed explanation of the concept or feature.

## Examples

```python
# Code examples here

Reference¶

API reference, parameters, return values, etc.

Best Practices¶

Guidelines and recommendations.

## Terminology Updates

The documentation has been updated to use consistent terminology:

- **Actions** instead of "handlers" - Functions that execute and produce outputs
- **Classifiers** - Nodes that route input to appropriate actions
- **Classifiers** - Nodes that route input to appropriate actions

## Navigation Structure

The documentation uses a hierarchical navigation structure defined in `mkdocs.yml`:

```yaml
nav:
  - Home: index.md
  - Quickstart: quickstart.md
  - Core Concepts:
      - Intent Graphs: concepts/intent-graphs.md
      - Nodes and Actions: concepts/nodes_and_handlers.md
      # ... more sections

Best Practices¶

Content Guidelines¶

Clear Titles - Use descriptive, action-oriented titles
Consistent Formatting - Follow markdown conventions
Code Examples - Include working, copy-pasteable examples
Cross-References - Link to related documentation
Status Tracking - Keep file status up to date

Organization Guidelines¶

Logical Grouping - Group related concepts together
Progressive Complexity - Start simple, build to advanced
Consistent Naming - Use consistent file and section names
Regular Updates - Keep documentation current with code changes

Maintenance Guidelines¶

Regular Reviews - Review and update documentation regularly
Validation - Run validation to check for missing files
Status Reports - Generate reports to track completion
Version Control - Commit documentation changes with code changes

Common Tasks¶

Adding New Documentation¶

Create the file using the management script
Write comprehensive content
Update the status to "complete"
Update navigation if needed

Updating Existing Documentation¶

Edit the file content
Update metadata if needed
Validate links and references
Test examples and code snippets

Reorganizing Documentation¶

Use the move command to relocate files
Update navigation structure
Update cross-references
Validate the new structure

Archiving Documentation¶

Move to appropriate archive section
Update navigation to remove from main sections
Add deprecation notices if needed
Update cross-references

Automation¶

The documentation system can be automated:

# Generate status report for CI/CD
python scripts/manage_docs.py report > docs_status.txt

# Validate before deployment
python scripts/manage_docs.py validate

# Create missing files from structure
python scripts/manage_docs.py create --section api --filename missing.md --title "Missing" --description "Auto-created"

Integration with Development¶

Documentation changes should be part of feature development
Update documentation when APIs change
Include documentation in code reviews
Test documentation examples in CI/CD