2:I[7012,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],"MarkdownRenderer"] 4:I[9856,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],""] 5:I[4126,[],""] 7:I[9630,[],""] 8:I[4278,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"HeadingProvider"] 9:I[1476,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Header"] a:I[3167,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Sidebar"] b:I[7409,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"PageFrame"] 3:T162e, # 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 ```bash # 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 | Metric | Description | Target | | ------------------ | ------------------------------------------ | ------- | | `health_status` | Overall health: healthy/warning/unhealthy | healthy | | `scores.overall` | Composite health score (0-100) | 80+ | | `scores.coverage` | Frontmatter completeness | 90+ | | `scores.freshness` | Docs updated within staleness threshold | 80+ | | `ai_coverage` | Docs with `ai_summary` / total AI-targeted | 85%+ | ### Freshness Scoring Docs are considered "stale" based on category-specific thresholds: | Category | Freshness Threshold | | ---------- | ------------------- | | API | 60 days | | Operations | 90 days | | Reference | 180 days | | Planning | 30 days | --- ## Validation Pipeline ### Available Commands From `apps/docs-site`: ```bash # 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 | Metric | Target | Description | | -------------------------- | ------ | -------------------------------------- | | `ai_summary` coverage | 85%+ | Docs with AI-optimized summaries | | `ai-agents` audience usage | 100% | AI-relevant docs tagged appropriately | | Schema compliance | 100% | All AI fields follow metadata standard | ### Improving AI Coverage 1. **Identify gaps**: ```bash 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](DOCUMENTATION_METADATA_STANDARD.md#ai-specific-fields) 3. **Regenerate**: ```bash pnpm generate-agent-json ``` --- ## Agent Endpoints Machine-readable documentation available at `https://assistdocs.asimo.io`: | Endpoint | Purpose | | --------------------------- | ----------------------------------------------- | | `/agent/index.json` | Discovery endpoint with schema definitions | | `/agent/docs.json` | Full doc list with metadata (incl `ai_summary`) | | `/agent/docs-summary.json` | AI summaries organized by category | | `/agent/health.json` | Health metrics and freshness scores | | `/agent/code-examples.json` | Code blocks extracted from docs | | `/agent/tasks.json` | Common agent tasks with commands | | `/agent/schema.json` | JSON Schema for response types | | `/search-index.json` | Fuse.js search index | See [Agent API Reference](ai/AGENT_API_REFERENCE.md) 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](INTERNAL_DOCS_SYSTEM.md) - Validation scripts and tooling - [Documentation Metadata Standard](DOCUMENTATION_METADATA_STANDARD.md) - Schema and field definitions - [Agent API Reference](ai/AGENT_API_REFERENCE.md) - Endpoint documentation - [Agent Task Index](ai/AGENT_TASK_INDEX.md) - Docs health audit task --- ## Version History | Version | Date | Changes | | ------- | ---------- | --------------- | | 1.0.0 | 2025-12-04 | Initial release | 6:["slug","DOCS_HEALTH_OVERVIEW","c"] 0:["X7oMT3VrOffzp0qvbeOas",[[["",{"children":["docs",{"children":[["slug","DOCS_HEALTH_OVERVIEW","c"],{"children":["__PAGE__?{\"slug\":[\"DOCS_HEALTH_OVERVIEW\"]}",{}]}]}]},"$undefined","$undefined",true],["",{"children":["docs",{"children":[["slug","DOCS_HEALTH_OVERVIEW","c"],{"children":["__PAGE__",{},[["$L1",["$","div",null,{"children":[["$","div",null,{"className":"mb-6 flex items-center justify-between gap-4","children":[["$","div",null,{"children":[["$","p",null,{"className":"text-sm text-gray-500 dark:text-gray-400","children":"Docs / Raw"}],["$","h1",null,{"className":"text-3xl font-bold text-gray-900 dark:text-white","children":"Documentation Health Overview"}],["$","p",null,{"className":"text-sm text-gray-600 dark:text-gray-400","children":["Sourced from"," ",["$","code",null,{"className":"font-mono text-xs","children":["docs/","DOCS_HEALTH_OVERVIEW.md"]}]]}]]}],["$","a",null,{"href":"https://github.com/mohammednazmy/VoiceAssist/edit/main/docs/DOCS_HEALTH_OVERVIEW.md","target":"_blank","rel":"noreferrer","className":"inline-flex items-center gap-2 rounded-md border border-gray-200 dark:border-gray-700 px-3 py-1.5 text-sm text-gray-700 dark:text-gray-200 hover:border-primary-500 dark:hover:border-primary-400 hover:text-primary-700 dark:hover:text-primary-300","children":"Edit on GitHub"}]]}],["$","div",null,{"className":"rounded-lg border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 p-6","children":["$","$L2",null,{"content":"$3"}]}],["$","div",null,{"className":"mt-6 flex flex-wrap gap-2 text-sm","children":[["$","$L4",null,{"href":"/reference/all-docs","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"← All documentation"}],["$","$L4",null,{"href":"/","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"Home"}]]}]]}],null],null],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children","$6","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[[[["$","link","0",{"rel":"stylesheet","href":"/_next/static/css/7f586cdbbaa33ff7.css","precedence":"next","crossOrigin":"$undefined"}]],["$","html",null,{"lang":"en","className":"h-full","children":["$","body",null,{"className":"__className_f367f3 h-full bg-white dark:bg-gray-900","children":[["$","a",null,{"href":"#main-content","className":"skip-to-content","children":"Skip to main content"}],["$","$L8",null,{"children":[["$","$L9",null,{}],["$","$La",null,{}],["$","main",null,{"id":"main-content","className":"lg:pl-64","role":"main","aria-label":"Documentation content","children":["$","$Lb",null,{"children":["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":"404"}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],"notFoundStyles":[]}]}]}]]}]]}]}]],null],null],["$Lc",null]]]] c:[["$","meta","0",{"name":"viewport","content":"width=device-width, initial-scale=1"}],["$","meta","1",{"charSet":"utf-8"}],["$","title","2",{"children":"Documentation Health Overview | Docs | VoiceAssist Docs"}],["$","meta","3",{"name":"description","content":"Overview of documentation health metrics, validation pipeline, and continuous improvement targets for VoiceAssist docs."}],["$","meta","4",{"name":"keywords","content":"VoiceAssist,documentation,medical AI,voice assistant,healthcare,HIPAA,API"}],["$","meta","5",{"name":"robots","content":"index, follow"}],["$","meta","6",{"name":"googlebot","content":"index, follow"}],["$","link","7",{"rel":"canonical","href":"https://assistdocs.asimo.io"}],["$","meta","8",{"property":"og:title","content":"VoiceAssist Documentation"}],["$","meta","9",{"property":"og:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","10",{"property":"og:url","content":"https://assistdocs.asimo.io"}],["$","meta","11",{"property":"og:site_name","content":"VoiceAssist Docs"}],["$","meta","12",{"property":"og:type","content":"website"}],["$","meta","13",{"name":"twitter:card","content":"summary"}],["$","meta","14",{"name":"twitter:title","content":"VoiceAssist Documentation"}],["$","meta","15",{"name":"twitter:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","16",{"name":"next-size-adjust"}]] 1:null