Documentation Guidelines

This guide provides standards and best practices for maintaining and contributing to Codomyrmex documentation.

📋 Documentation Philosophy

Core Principles

User-Centric: Documentation is organized by user intent, not code structure
Show, Don't Tell: Provide working examples rather than abstract descriptions
Progressive Complexity: Start simple, build to advanced topics
Maintenance-First: Easy to maintain and keep up-to-date
Accessible: Clear language, good structure, searchable content

Documentation Types

Type	Location	Purpose	Audience
Project Documentation	`docs/`	Information about Codomyrmex	Users, Contributors
Module Documentation	`src/codomyrmex/[module]/`	Module-specific information	Module users
Documentation Tools	`src/codomyrmex/documentation/`	Website generation tools	Other projects
API References	`*/API_SPECIFICATION.md`	Technical API details	Developers

Mermaid diagrams (`docs/`)

Diagrams use fenced code blocks with the mermaid language tag. Conventions:

No hard-coded theme styling — Do not use style … fill:…, classDef, or :::class on nodes. Diagrams must render legibly in light and dark themes (see Cursor Mermaid rules).
Subgraphs — Prefer subgraph graphId [Human-readable label] so the graph id has no spaces and labels with punctuation stay in brackets.
Edges and nodes — Use quoted edge labels when they contain parentheses or slashes. Avoid node ids that are Mermaid reserved words (end, graph, …).
Edges only between real nodes — Do not point an edge at a subgraph name unless your renderer supports it; connect to an explicit node inside the subgraph instead.
Maintenance scripts (repo root): uv run python scripts/strip_mermaid_style_lines.py removes legacy style lines; uv run python scripts/normalize_mermaid_subgraphs.py converts subgraph "Title" to subgraph sg_… [Title].

Documentation metrics (inventory)

Counts for modules, MCP tools, and tests drift quickly. Do not hand-edit broad statistics across the tree — refresh from one place:

docs/reference/inventory.md — definitions, dated table, reproduce commands
uv run python scripts/doc_inventory.py — print current counts (--pytest includes collected test total, ~30s)

Hermes-specific examples and agent-doc rules: docs/agents/hermes/AGENTS.md (Diagram conventions).

Generated site output (Docusaurus)

Paths such as src/codomyrmex/documentation/.docusaurus/ are build output from the site generator, not editorial sources. Do not treat files there (including any AGENTS.md copies) as maintained RASP contracts. Edit hand-written docs under docs/ and per-module files under src/codomyrmex/<module>/ instead.

🏗️ Documentation Structure

Main Documentation (`docs/`)

docs/
├── README.md                     # Documentation overview
├── getting-started/              # User onboarding
│   ├── installation.md           # Installation guide
│   ├── quickstart.md             # Quick start guide
│   └── tutorials/                # Step-by-step tutorials
├── project/                      # Project-level documentation
│   ├── architecture.md           # System architecture
│   └── contributing.md           # Contributing guidelines
├── modules/                      # Module system documentation
│   ├── overview.md               # Module system overview
│   └── relationships.md          # Inter-module dependencies
├── development/                  # Developer documentation
│   ├── environment-setup.md      # Development environment
│   └── documentation.md          # This file
└── reference/                    # Reference materials
    ├── troubleshooting.md        # Troubleshooting guide
    ├── cli.md                    # CLI reference
    ├── api.md                    # API reference index
    └── changelog.md              # Version history (redirects to root)

Module Documentation Pattern

Each module follows this standardized documentation structure:

src/codomyrmex/[module]/
├── README.md                     # ✅ REQUIRED: Module overview
├── AGENTS.md                     # ✅ REQUIRED: Agent configuration
├── SECURITY.md                   # ✅ REQUIRED: Security considerations
├── API_SPECIFICATION.md          # ⚠️ Required if referenced in docs/index.md
├── MCP_TOOL_SPECIFICATION.md     # ⚠️ Required if referenced in docs/index.md
├── USAGE_EXAMPLES.md             # ⚠️ Required if referenced in docs/index.md
├── CHANGELOG.md                  # Optional: Module version history
├── pyproject.toml              # Project dependencies
├── docs/                         # Extended documentation
│   ├── index.md                  # ✅ REQUIRED if docs/ exists
│   ├── technical_overview.md     # Optional: Architecture details
│   └── tutorials/                # Optional: Module-specific tutorials
│       └── example_tutorial.md   # ⚠️ Required if referenced in docs/index.md
└── tests/
    └── README.md                 # Optional: Testing documentation

Required Files

All modules MUST have:

README.md: Module overview, features, quick start, and usage examples
AGENTS.md: Agent configuration, operating contracts, and navigation links
SPEC.md: Functional specification and design principles
PAI.md: Personal AI Infrastructure integration notes
SECURITY.md: Security considerations and vulnerability reporting process

Conditionally Required Files

These files are required if referenced in documentation:

API_SPECIFICATION.md: Required if docs/index.md references it
MCP_TOOL_SPECIFICATION.md: Required if docs/index.md references it
USAGE_EXAMPLES.md: Required if docs/index.md references it
docs/tutorials/example_tutorial.md: Required if docs/index.md references it

Link Standards

All internal links must follow these conventions:

Contributing Guidelines: Always link to ../../docs/project/contributing.md (from module root) or ../../../docs/project/contributing.md (from docs/ directory)
Module Documentation: Use relative paths from current file location
Cross-Module References: Use paths relative to repository root

Validation

Module documentation is automatically validated using:

scripts/documentation/module_docs_auditor.py - Comprehensive audit tool
scripts/documentation/validate_module_docs.py - CI/CD validation tool

Run validation before committing:

python3 scripts/documentation/validate_module_docs.py

RASP folder gap scan

After large doc-tree changes, regenerate the scoped AGENTS.md / README.md presence report:

uv run python scripts/rasp_gap_report.py

Output: docs/plans/agents-readme-gap-report.md. Inclusion roots and path excludes are defined in scripts/rasp_gap_report.py.

✍️ Writing Standards

Markdown Style

# Document Title

Brief description of what this document covers.

## 🎯 Section with Emoji

Use descriptive emojis to make sections scannable.

### **Bold Subsection Headers**

Use bold for important subsections.

#### Regular Subsection

Use regular headers for detailed breakdowns.

### **Code Examples**

```python
# Always include complete, working examples
from codomyrmex.module import function

result = function("example", param="value")
print(f"Result: {result}")

Tables for Reference Information

Column 1	Column 2	Column 3
Data	Data	Data

Callout Boxes

⚠️ Important: Critical information users must know.

💡 Tip: Helpful suggestions for better experience.

🔍 Note: Additional context or clarification.


### **Link Conventions**

```markdown
# Internal links (relative to current file)
[Architecture Guide](../project/architecture.md)
[Module Template](../../src/codomyrmex/module_template/README.md)

# External links
[GitHub Repository](https://github.com/docxology/codomyrmex)

# Anchor links within document
[See Installation Section](#installation)

Code Example Standards

Complete Examples: Always provide full, runnable code
Real Implementations: No placeholder or pseudo-code
Error Handling: Show proper error handling patterns
Context: Provide necessary imports and setup

# ✅ Good example
from codomyrmex.logging_monitoring import setup_logging, get_logger
from codomyrmex.data_visualization import create_line_plot
import numpy as np

# Initialize logging (required)
setup_logging()
logger = get_logger(__name__)

try:
    # Generate sample data
    x = np.linspace(0, 10, 100)
    y = np.sin(x)
    
    # Create visualization
    create_line_plot(
        x_data=x, 
        y_data=y, 
        title="Sine Wave",
        output_path="sine_wave.png"
    )
    logger.info("Plot created successfully")
    
except Exception as e:
    logger.error(f"Failed to create plot: {e}")
    raise

# ❌ Bad example
result = some_function()
print(result)

🔍 Quality Assurance

Documentation Review Checklist

Accuracy: All code examples work
Completeness: Covers all necessary information
Clarity: Clear, concise writing
Structure: Logical organization and flow
Links: All internal links work correctly
Consistency: Follows established patterns
User-Focused: Addresses user needs and questions
Examples: Includes practical, working examples
Maintenance: Easy to keep up-to-date

Module Documentation Validation

All module documentation is validated for consistency and completeness:

Automated Validation Tools

scripts/documentation/module_docs_auditor.py: Comprehensive audit of all modules
- Scans for missing required files
- Identifies broken references
- Checks documentation structure
- Generates detailed reports
scripts/documentation/validate_module_docs.py: Fast validation for CI/CD
- Validates required files exist
- Checks for broken references
- Ensures link consistency
- Returns exit code for automation

Running Validation

# Comprehensive audit (generates detailed report)
python3 scripts/documentation/module_docs_auditor.py

# Quick validation (for CI/CD)
python3 scripts/documentation/validate_module_docs.py

# Fix common issues
python3 scripts/documentation/fix_contributing_refs.py
python3 scripts/documentation/create_example_tutorials.py
python3 scripts/documentation/create_missing_doc_files.py

Link Validation

Regular link checking is essential:

# Manual link checking
find docs/ -name "*.md" -exec grep -l "](.*\.md)" {} \; | while read file; do
    echo "Checking links in $file"
    grep -o "](.*\.md)" "$file" | sed 's/](\(.*\))/\1/' | while read link; do
        if [[ ! -f "$(dirname "$file")/$link" ]] && [[ ! -f "$link" ]]; then
            echo "❌ Broken link: $link in $file"
        fi
    done
done

# Check external links (requires network)
# Use tools like markdown-link-check or similar

Content Maintenance

Regular Reviews: Schedule quarterly documentation reviews
Version Sync: Update documentation with code changes
Link Maintenance: Check for broken links after file moves
Example Validation: Test all code examples regularly
User Feedback: Incorporate user feedback and questions

Automated Maintenance

The documentation system includes automated tools for maintenance:

Pre-Commit Validation

# Add to .git/hooks/pre-commit
python3 scripts/documentation/validate_module_docs.py

CI/CD Integration

See .github/workflows/documentation-validation.yml for automated validation in CI/CD pipelines.

Regular Audits

Run comprehensive audits periodically:

# Full repository audit
python3 scripts/documentation/comprehensive_audit.py

# Module-specific audit
python3 scripts/documentation/module_docs_auditor.py

🚀 Contributing Documentation

Quick Contribution Process

Identify Gap: Find missing or outdated documentation
Check Structure: Determine correct location in documentation structure
Write Content: Follow the writing standards above
Test Examples: Ensure all code examples work
Check Links: Verify all links work correctly
Submit PR: Create pull request with clear description

Major Documentation Changes

Discuss First: Open issue to discuss major structural changes
Plan Migration: Consider impact on existing links and bookmarks
Update References: Update all referring documentation
Provide Redirects: Add redirect notices for moved content
Announce Changes: Communicate changes to community

Documentation Tools

# Local documentation development
cd src/codomyrmex/documentation/
npm install
npm run start  # Start development server

# Build documentation website
npm run build

# Check for broken links (if using link checker)
npm run check-links

🔧 Maintenance Tasks

Regular Maintenance Schedule

Weekly

Check for new issues asking documentation questions
Review and merge documentation pull requests
Update example code if APIs change

Monthly

Run comprehensive link checking
Review analytics for most-viewed documentation
Update getting-started guides for new features

Quarterly

Complete documentation structure review
User experience testing with new contributors
Performance review of documentation website
Cleanup of outdated or redundant content

Documentation Metrics

Track these metrics for documentation health:

Coverage: Percentage of modules with complete documentation
Freshness: Age of documentation vs. last code changes
Usage: Most and least viewed documentation pages
Issues: Number of documentation-related issues opened
Contribution: Community contributions to documentation

Common Issues and Solutions

Outdated Examples

Problem: Code examples break with API changes
Solution: Automated testing of documentation examples
Prevention: Include documentation in code review process

Broken Links

Problem: Links break when files are moved or reorganized
Solution: Regular link checking and relative link preferences
Prevention: Use consistent link patterns and automation

Structure Confusion

Problem: Users can't find information they need
Solution: User testing and feedback collection
Prevention: User-centric organization and clear navigation

Duplicate Content

Problem: Information exists in multiple places, creating maintenance burden
Solution: Single source of truth principle
Prevention: Clear content ownership and regular audits

🎯 Success Metrics

Good documentation should achieve:

Discoverability: Users can quickly find what they need
Usability: Information is clear and actionable
Completeness: All necessary information is available
Maintainability: Easy to keep up-to-date
Community: Encourages contributions and engagement

User Success Indicators

Decreased "documentation" issues in GitHub
Increased successful first-time installations
More community contributions
Positive feedback on documentation quality
Reduced support requests for covered topics

Last Updated: Auto-generated from documentation review
Maintainers: Documentation team and community contributors
Feedback: Open an issue for documentation improvements

Navigation Links

Parent: Project Overview
Module Index: All Agents
Documentation: Reference Guides
Home: Repository Root

FilesExpand file tree

documentation.md

Latest commit

History