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:T141b, # VoiceAssist Documentation Style Guide This guide establishes consistent writing standards for all VoiceAssist documentation, ensuring clarity for both human readers and AI agents. ## Document Structure ### Required Frontmatter Every markdown document MUST include frontmatter: ```yaml --- title: Document Title (required) status: draft|experimental|stable|deprecated (required) lastUpdated: YYYY-MM-DD (required) audience: [list of target readers] (required) category: category-slug (required) owner: team-name (required) summary: Brief description (required for key docs) --- ``` ### Valid Values **Status:** - `draft` - Work in progress, not reviewed - `experimental` - New content, subject to change - `stable` - Reviewed and maintained - `deprecated` - Outdated, pending removal **Audience:** - `developers` - Software engineers - `admin` - System administrators - `ai-agents` - AI/LLM consumers - `user` - End users - `frontend` - Frontend developers - `backend` - Backend developers - `devops` - DevOps/SRE engineers **Category:** - `overview` - High-level documentation - `reference` - API/technical reference - `architecture` - System design - `deployment` - Installation/deployment - `security` - Security documentation - `feature-flags` - Feature flag documentation - `testing` - Testing guides ## Writing Standards ### Voice and Tone - Use **active voice**: "The API returns a JSON response" not "A JSON response is returned by the API" - Be **direct and concise**: Get to the point quickly - Use **present tense**: "This function validates..." not "This function will validate..." - Be **objective**: Focus on facts, not opinions ### Formatting #### Headings ```markdown # Page Title (H1 - only one per document) ## Major Section (H2) ### Subsection (H3) #### Detail (H4 - use sparingly) ``` #### Code Blocks Always specify language for syntax highlighting: ```typescript // TypeScript example function example(): void { console.log("Hello"); } ``` ```bash # Shell commands npm run build ``` #### Lists Use bullet points for unordered items: - Item one - Item two Use numbered lists for sequential steps: 1. First step 2. Second step #### Tables Use tables for structured comparisons: | Column A | Column B | Column C | | -------- | -------- | -------- | | Value 1 | Value 2 | Value 3 | ### URLs and Links - Use canonical URLs as defined in the plan: - Web app: `https://dev.asimo.io` - API: `https://assist.asimo.io` - Admin: `https://admin.asimo.io` - Docs: `https://assistdocs.asimo.io` - Use relative links for internal docs: `[Related Doc](./related-doc.md)` - Use absolute URLs for external resources ### Code References When referencing code: - Use backticks for inline code: `functionName()` - Include file paths: `services/api-gateway/src/routes.ts:42` - Link to source when helpful ### API Documentation Follow this structure for endpoints: ````markdown ### POST /api/resource Create a new resource. **Request:** ```json { "name": "string", "value": "number" } ``` ```` **Response (200):** ```json { "id": "string", "name": "string", "created_at": "ISO-8601" } ``` **Errors:** - `400` - Invalid request body - `401` - Unauthorized - `500` - Server error ```` ## AI Agent Considerations Documentation should be consumable by AI agents: ### Machine-Readable Summaries Include `ai_summary` in frontmatter for key documents: ```yaml ai_summary: "API Gateway handles auth, rate limiting, and routing. Main entry point at /api/*. Uses JWT tokens. See routes.ts for all endpoints." ```` ### Structured Information Use consistent patterns AI can parse: - **Definition lists** for terminology - **Tables** for comparisons - **Code blocks** for examples - **Frontmatter** for metadata ### Avoid - Ambiguous pronouns ("it", "this") without clear referents - Implicit knowledge assumptions - Colloquialisms and idioms ## File Naming - Use **lowercase** with **hyphens**: `feature-flags.md` - Be **descriptive**: `api-authentication-guide.md` not `auth.md` - Match the title: Title "API Guide" = file `api-guide.md` ## Images and Diagrams - Store in `/docs/assets/images/` - Use descriptive filenames: `architecture-overview.png` - Include alt text: `![Architecture diagram showing service connections](./assets/images/architecture-overview.png)` - Prefer SVG for diagrams when possible ## Versioning For versioned documentation: - Use URL paths: `/v1/api-reference.md`, `/v2/api-reference.md` - Mark old versions as deprecated - Link to latest version prominently ## Review Checklist Before publishing: - [ ] Frontmatter complete and valid - [ ] No broken internal links - [ ] Code examples are correct and tested - [ ] URLs use canonical domains - [ ] Spelling and grammar checked - [ ] Technical accuracy verified - [ ] AI-readable (clear summaries, structured data) ## Tools ### Validation ```bash # Validate frontmatter npm run validate:docs # Check links npm run check:links # Lint markdown npm run lint:docs ``` ### Generation ```bash # Generate agent JSON npm run generate:agent # Update search index npm run build:search ``` 6:["slug","STYLE_GUIDE","c"] 0:["X7oMT3VrOffzp0qvbeOas",[[["",{"children":["docs",{"children":[["slug","STYLE_GUIDE","c"],{"children":["__PAGE__?{\"slug\":[\"STYLE_GUIDE\"]}",{}]}]}]},"$undefined","$undefined",true],["",{"children":["docs",{"children":[["slug","STYLE_GUIDE","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":"VoiceAssist Documentation Style Guide"}],["$","p",null,{"className":"text-sm text-gray-600 dark:text-gray-400","children":["Sourced from"," ",["$","code",null,{"className":"font-mono text-xs","children":["docs/","STYLE_GUIDE.md"]}]]}]]}],["$","a",null,{"href":"https://github.com/mohammednazmy/VoiceAssist/edit/main/docs/STYLE_GUIDE.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":"VoiceAssist Documentation Style Guide | Docs | VoiceAssist Docs"}],["$","meta","3",{"name":"description","content":"Writing standards for VoiceAssist documentation"}],["$","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