Documentation Health Overview

This document provides a single-page overview of documentation health metrics, validation processes, and improvement targets for the VoiceAssist documentation system.

Quick Health Check

# Check live health metrics
curl https://assistdocs.asimo.io/agent/health.json | jq '.health_status, .scores'

# Run local validation
cd apps/docs-site && pnpm validate:all

# Check AI summary coverage
curl https://assistdocs.asimo.io/agent/docs-summary.json | jq '.stats'

Health Metrics

The documentation system tracks several health metrics, available via /agent/health.json:

Key Metrics

Freshness Scoring

Docs are considered "stale" based on category-specific thresholds:

Validation Pipeline

Available Commands

From apps/docs-site:

# Individual checks
pnpm validate:metadata    # Frontmatter schema validation
pnpm check:links          # Internal link verification
pnpm check:freshness      # Staleness detection
pnpm validate:api-sync    # API docs vs OpenAPI spec
pnpm validate:api-sync --strict  # Strict mode (fails on drift)

# Combined validation
pnpm validate:all         # All checks in sequence

# Generation
pnpm generate-search-index  # Rebuild search index
pnpm generate-agent-json    # Rebuild agent JSON endpoints

What validate:metadata Checks

• Required fields: title, slug, status, lastUpdated
• Enum values: status, stability, owner, category
• Array fields: audience, tags, relatedServices
• Date format: ISO 8601 (YYYY-MM-DD)
• AI-specific: Warns if audience includes ai-agents but ai_summary is missing

CI Integration

Validation runs automatically on:

• Pull requests touching docs/**
• Pre-commit hooks (if configured)
• Build pipeline (pnpm build calls validate:all via prebuild)

AI-Docs Coverage

Target Metrics

Improving AI Coverage

1. Identify gaps:

   pnpm validate:metadata 2>&1 | grep "Missing ai_summary"

2. Add ai_summary to docs targeting AI agents:

   • 2-3 sentences
   • Technical and concise
   • Include key facts and cross-references
   • See Metadata Standard

3. Regenerate:

   pnpm generate-agent-json

Agent Endpoints

Machine-readable documentation available at https://assistdocs.asimo.io:

See Agent API Reference for detailed endpoint documentation.

Continuous Improvement

Regular Tasks

1. Weekly: Run pnpm validate:all and address warnings
2. Monthly: Review /agent/health.json freshness scores
3. Quarterly: Audit ai_summary coverage and update stale docs

Improvement Priorities

1. High: Fix validation errors (block CI)
2. Medium: Address freshness warnings in critical categories
3. Low: Add ai_summary to docs missing it

Known TODOs

• ✅ All docs now have ai_summary (100% coverage as of 2025-12-05)
• Consider automating ai_summary generation for new docs
• Monitor freshness scores to catch stale docs early

Related Documentation

• Internal Documentation System - Validation scripts and tooling
• Documentation Metadata Standard - Schema and field definitions
• Agent API Reference - Endpoint documentation
• Agent Task Index - Docs health audit task

Version History