Documentation Guide¶

Rules and conventions for writing Omni documentation — for both human authors and AI assistants.

General Rules (Human & AI)¶

Structure¶

• One topic per page — Don't combine unrelated content in a single file
• Use the established nav hierarchy in mkdocs.yml — add new pages there
• Frontmatter — Use YAML frontmatter for page-level overrides (e.g., hide: [toc])
• Headings — Start with # H1 (one per page), then ## H2, ### H3. Never skip levels
• Table of contents — Every page with 3+ sections should have a ToC (automatic via mkdocs-material)

Writing Style¶

• Active voice — "The agent sends a message" not "A message is sent by the agent"
• Present tense — "The backend validates the token" not "The backend will validate the token"
• Second person for guides — "You can configure..." for tutorials
• Third person for architecture — "The system uses..." for technical docs
• Be concise — Prefer short sentences. Cut filler words
• Code over prose — Show a code example instead of describing behavior in paragraphs

Formatting¶

• Code blocks — Always specify the language: ```python, ```bash, ```json
• Inline code — Use backticks for: file names, function names, variable names, CLI commands, config keys
• Tables — Use Markdown tables for structured comparisons (not bullet lists)

• Admonitions — Use mkdocs-material admonitions for callouts:

  !!! tip "Helpful hint"
      This is a tip.
  
  !!! warning "Be careful"
      This could cause issues.
  
  !!! note "Additional context"
      Extra information here.
  

• Links — Use relative paths for internal links: [Installation](../getting-started/installation.md)

• Lists — Use - for unordered lists, 1. for ordered lists

Rules for AI-Generated Content¶

When documentation is generated or significantly written by AI, follow these additional rules:

Images and Diagrams¶

Format for image placeholders:

<!-- IMAGE: A system architecture diagram showing the flow from 5 client types 
(web, desktop, chrome extension, smart glasses, CLI) connecting via WebSocket 
to a central FastAPI backend, which fans out to Google ADK, MCP Plugin Registry, 
and E2B Sandbox services. The backend connects to Gemini Live API and Vertex AI 
on the right. Use a dark theme with purple (#7c3aed) accent colors, flat modern 
design, 1200x800px, white text on dark background. -->

For diagrams, prefer Mermaid over images:

​```mermaid
graph LR
    A[Client] --> B[Backend]
    B --> C[Gemini API]
​```

AI Authoring Markers¶

• DO NOT add "Generated by AI" markers to individual pages — the docs should read as authoritative project documentation
• DO add AI generation prompts as HTML comments (invisible in rendered output) where images/diagrams are needed
• If AI generates a page, a human should review it before merging

Content Accuracy¶

• Verify all code examples — Every code block must be correct and runnable
• Check all paths — File paths, URLs, and API endpoints must match the actual codebase
• Cross-reference — If you mention a feature, link to its documentation page

• No hallucinated features — Only document what actually exists in the codebase. If a feature is planned, mark it clearly:

  !!! warning "Planned feature"
      This feature is not yet implemented. See [issue #123](#) for progress.
  

Mermaid Diagram Standards¶

• Use graph TB or graph LR for architecture diagrams
• Use sequenceDiagram for protocol flows
• Use flowchart for decision trees
• Keep diagrams under 20 nodes — split complex diagrams into multiple simpler ones
• Use subgraphs to group related components

Rules for Human Authors¶

Before Writing¶

1. Check if a page already exists for your topic
2. Read the existing pages in the same section for tone/style consistency
3. Plan the page structure: H1 → H2s → content under each

Screenshots¶

• Capture at 2x resolution if possible (Retina/HiDPI)
• Crop tightly — Only show the relevant UI area
• Add to docs/assets/ — Organize in subdirectories by section: docs/assets/guides/, docs/assets/architecture/
• Use descriptive filenames — plugin-store-overview.png not screenshot1.png
• Alt text — Always provide descriptive alt text: ![Plugin store showing available MCP plugins](assets/guides/plugin-store-overview.png)
• Max width — Images should not exceed 1200px wide

Code Examples¶

• Test your code — Every code block should be copy-pasteable and functional

• Use annotations — mkdocs-material supports code annotations:

  def create_agent(persona): # (1)!
      tools = build_tools(persona.capabilities) # (2)!
      return Agent(tools=tools)
  

  1. Takes a persona config object
  2. Builds the tool list from capability tags

Review Process¶

1. Create a branch: docs/your-topic
2. Write or edit pages
3. Preview locally: mkdocs serve
4. Open a PR — docs are auto-deployed on merge to main

File Organization¶

site-docs/
├── index.md                          # Home page
├── requirements.txt                  # Python deps for mkdocs
├── stylesheets/
│   └── extra.css                     # Custom CSS
├── assets/                           # Images and static files
│   ├── architecture/
│   ├── guides/
│   └── screenshots/
├── getting-started/
│   ├── index.md
│   ├── installation.md
│   └── quickstart.md
├── architecture/
│   ├── index.md
│   ├── backend.md
│   ├── dashboard.md
│   ├── desktop-client.md
│   ├── chrome-extension.md
│   └── smart-glasses.md
├── guides/
│   ├── plugin-development.md
│   ├── mcp-server-development.md
│   ├── client-development.md
│   ├── frontend-development.md
│   ├── agent-personas.md
│   └── genui-components.md
├── api/
│   ├── rest.md
│   ├── websocket.md
│   └── desktop-tools.md
├── deployment/
│   ├── gcp-setup.md
│   ├── docker.md
│   └── terraform.md
└── contributing/
    ├── documentation-guide.md        # ← This file
    └── development-setup.md

Local Preview¶

pip install -r site-docs/requirements.txt
mkdocs serve

Open http://localhost:8000 to preview the docs with live reload.

Deployment¶

Docs auto-deploy to GitHub Pages on push to main via GitHub Actions. See .github/workflows/docs.yml.