Megadoc Architecture and Documentation Standards

This document defines the architecture for ohemr-epic-megadoc (the unified documentation portal) and establishes strict standards for documentation structure, content generation, and maintenance across all Optum Tech Compute repositories.

Architecture Overview

The Megadoc Pattern

ohemr-epic-megadoc/ (BASE REPO)
├── mkdocs.yml           ← PARENT CONFIGURATION (navigation, theme, plugins)
├── docs/
│   ├── index.md
│   └── base-content/
└── submodules/          ← IMPORTED REPOSITORY DOCUMENTATION
    ├── ohemr-ansible-playbooks/
    │   └── docs/        ← Content only, no mkdocs.yml control
    ├── otc-awesome-llm/
    │   └── docs/
    └── (137 other repos)/
        └── docs/

Critical Principle: Separation of Concerns

Component	Responsibility	Owner
Base Repo (ohemr-epic-megadoc)	Parent mkdocs.yml, navigation structure, theme, plugins, site generation	Documentation Team
Submodules (all other repos)	Documentation content only in docs/ directory	Repository Owners
Submodule mkdocs.yml	Minimal stubs for local dev only (name, site_url, optional nav preview)	Repository Owners

Base Repository Ownership

ohemr-epic-megadoc Responsibilities

OWNS (Authoritative):

• ✅ Parent mkdocs.yml with complete navigation hierarchy
• ✅ MkDocs theme configuration (Material for MkDocs)
• ✅ MkDocs plugins (search, minify, git-revision-date, etc.)
• ✅ Site-wide navigation structure
• ✅ Landing pages and cross-repository index pages
• ✅ Build/deployment pipeline
• ✅ Custom CSS/JavaScript for site-wide features

Example Parent mkdocs.yml:

site_name: OHEMR Epic Platform Documentation
site_url: https://ohemr-epic-megadoc.optum.com
site_description: Unified documentation portal for Epic on Azure platform

# Theme configuration (BASE REPO ONLY)
theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - search.suggest
    - search.highlight

# Plugins (BASE REPO ONLY)
plugins:
  - search
  - minify
  - git-revision-date-localized
  - awesome-pages # Allows .pages files in submodules

# Navigation (BASE REPO CONTROLS)
nav:
  - Home: index.md
  - Getting Started:
      - Overview: getting-started/overview.md
      - Installation: getting-started/installation.md
  - Ansible Playbooks:
      - Overview: submodules/ohemr-ansible-playbooks/docs/index.md
      - Tutorials: submodules/ohemr-ansible-playbooks/docs/tutorials/
      - How-To Guides: submodules/ohemr-ansible-playbooks/docs/how-to/
      - Reference: submodules/ohemr-ansible-playbooks/docs/reference/
  - LLM Tooling:
      - Overview: submodules/otc-awesome-llm/docs/index.md
      - Getting Started: submodules/otc-awesome-llm/docs/getting-started/
  # ... 135 more repositories

Submodule Repository Standards

What Belongs in Submodule Repos

OWNS (Authoritative):

• ✅ All documentation content in docs/ directory
• ✅ Diataxis-structured subdirectories (tutorials, how-to, reference, explanation)
• ✅ YAML front-matter in all markdown files
• ✅ Images, diagrams, and assets in docs/assets/
• ✅ Code examples and snippets
• ✅ Minimal mkdocs.yml stub for local development

MUST NOT OWN:

• ❌ Theme configuration (inherited from base repo)
• ❌ Plugin configuration (inherited from base repo)
• ❌ Site-wide navigation (controlled by base repo)
• ❌ Custom CSS/JavaScript (base repo controls site appearance)

Minimal Submodule mkdocs.yml (Stub Only)

# ohemr-ansible-playbooks/mkdocs.yml
# STUB ONLY - For local development preview
# Parent mkdocs.yml in ohemr-epic-megadoc controls site generation

site_name: OHEMR Ansible Playbooks
site_url: https://ohemr-epic-megadoc.optum.com/ansible-playbooks
site_description: Ansible automation for Epic on Azure

# Optional: Navigation preview for local development
# (Ignored by parent build)
nav:
  - Home: index.md
  - Tutorials: tutorials/
  - How-To Guides: how-to/
  - Reference: reference/
  - Explanation: explanation/

# Do NOT configure:
# - theme (use defaults for local preview)
# - plugins (not needed for local preview)
# - custom_dir, extra_css, extra_javascript

Why This Matters

Problem Prevented:

• ❌ Submodules can't override parent theme/navigation
• ❌ Prevents documentation fragmentation
• ❌ Avoids "works locally, breaks in megadoc" issues
• ❌ Eliminates merge conflicts in theme configuration

Benefit Achieved:

• ✅ Single source of truth for site structure
• ✅ Consistent appearance across all documentation
• ✅ Submodules focus on content, not configuration
• ✅ Easy local development with mkdocs serve in submodule

Documentation Structure Standards

Diataxis Framework (MANDATORY)

All documentation MUST follow Diataxis structure:

docs/
├── index.md                 ← Overview and navigation
├── tutorials/               ← LEARNING-ORIENTED (teaching)
│   ├── index.md
│   └── getting-started.md
├── how-to/                  ← TASK-ORIENTED (solving problems)
│   ├── index.md
│   ├── how-to-deploy.md
│   └── how-to-troubleshoot.md
├── reference/               ← INFORMATION-ORIENTED (describing)
│   ├── index.md
│   ├── api-reference.md
│   └── configuration.md
├── explanation/             ← UNDERSTANDING-ORIENTED (discussing)
│   ├── index.md
│   └── architecture.md
└── assets/                  ← Images, diagrams
    └── images/

Diataxis Categories Explained

Tutorials - Learning by doing

• Goal: Teach a complete beginner
• Format: Step-by-step walkthrough
• Example: "Your First Ansible Playbook for Epic ODB"
• Audience: Someone new to the technology

How-To Guides - Solving specific problems

• Goal: Solve a real-world task
• Format: Recipe/checklist format
• Example: "How to Deploy Epic ODB Snapshot"
• Audience: Someone who knows basics, needs to accomplish task

Reference - Technical specifications

• Goal: Provide accurate, complete information
• Format: Dry, factual, comprehensive
• Example: "AWX Job Template Configuration Reference"
• Audience: Someone looking up specific details

Explanation - Understanding concepts

• Goal: Illuminate and clarify
• Format: Narrative, discussion-oriented
• Example: "Why We Use Hub-Spoke Network Architecture"
• Audience: Someone who wants deeper understanding

File Naming Conventions

In docs/ Directories

RULES:

• ✅ Lowercase only: getting-started.md, api-reference.md
• ✅ Hyphens for spaces: how-to-deploy-odb.md not How To Deploy ODB.md
• ✅ Underscores allowed: epic_odb_architecture.md (but prefer hyphens)
• ✅ Use index.md not README.md: docs/tutorials/index.md
• ✅ No spaces: user-guide.md not user guide.md
• ✅ Descriptive names: odb-snapshot-procedure.md not procedure.md

CORRECT:

docs/tutorials/getting-started-with-ansible.md
docs/how-to/how-to-create-awx-job-template.md
docs/reference/epic-odb-configuration.md
docs/explanation/network-architecture.md

INCORRECT:

docs/tutorials/Getting Started With Ansible.md       # Spaces, capitals
docs/how-to/Creating AWX Job Templates.md             # Spaces, capitals
docs/reference/README.md                              # Use index.md instead
docs/explanation/Architecture Details.md              # Spaces

GitHub Documentation Files (Root Level)

EXCEPTION: Standard GitHub files in repository root use UPPERCASE:

• ✅ README.md (repository overview, GitHub displays this)
• ✅ CONTRIBUTING.md (contribution guidelines)
• ✅ CHANGELOG.md (version history)
• ✅ LICENSE.md (software license)
• ✅ CODE_OF_CONDUCT.md (community guidelines)

DO NOT change these to lowercase or move to docs/

YAML Front-Matter (MANDATORY)

Every markdown file in docs/ MUST include complete front-matter:

---
title: Getting Started with Epic Ansible Playbooks
description: Complete tutorial for running your first Epic Ansible playbook
author: epic-platform-sre
date_created: '2026-01-12'
last_updated: '2026-01-12'
tags: [tutorial, ansible, epic, getting-started]
category: tutorials
status: published # draft | published | deprecated
version: '1.0'
diataxis_type: tutorial # tutorial | how-to | reference | explanation
---

Required Fields:

• title - Human-readable page title
• description - Brief summary (used for SEO, search)
• author - Team or individual owner
• last_updated - ISO date format (YYYY-MM-DD)
• tags - List of searchable keywords
• diataxis_type - Which Diataxis category

Optional but Recommended:

• date_created - Original creation date
• category - Grouping within Diataxis type
• status - Publication status
• version - Content version for tracking changes

Content Quality Standards

Review and Update Cycle

All documentation MUST:

• ✅ Be reviewed annually (update last_updated date)
• ✅ Mark outdated content with deprecation notice:

> **⚠️ DEPRECATED**: This document describes the old AWX 21.x workflow.
> For AWX 22.x+ (current), see [Modern AWX Workflow](new-workflow.md).
> This document will be removed on 2027-01-01.

• ✅ Remove content older than 2 years if deprecated
• ✅ Archive historical docs in docs/archive/ if needed for reference

Cleaning Up Old Documentation

When you encounter old/outdated docs:

1. Identify: Check last_updated date, version references, screenshots

2. Assess:

   • Still accurate? → Update last_updated date
   • Partially outdated? → Update content, note changes in CHANGELOG
   • Completely outdated? → Deprecate or remove

3. Update or Deprecate:

   > **📅 Last Verified**: 2024-03-15
   > **⚠️ Note**: Screenshots show AWX 21.x UI. Functionality is identical in 22.x.
   

4. Remove if:

   • Technology no longer used
   • Replaced by better documentation
   • Contains incorrect/dangerous information

LLM Documentation Generation Guidelines

When Using LLMs to Generate/Update Documentation

LLMs (Claude, ChatGPT, Copilot, Codex, etc.) MUST follow these rules:

1. Always Follow Diataxis Structure

Determine document type first:

• Teaching a beginner? → docs/tutorials/
• Solving a specific problem? → docs/how-to/
• Providing technical specs? → docs/reference/
• Explaining concepts? → docs/explanation/

Use correct file location:

<!-- CORRECT -->

docs/tutorials/getting-started.md
docs/how-to/deploy-odb-snapshot.md

<!-- INCORRECT -->

docs/getting-started.md # Missing Diataxis directory
docs/deploy.md # Ambiguous category

2. Generate Complete Front-Matter

ALWAYS include full front-matter:

---
title: How to Deploy Epic ODB Snapshot
description: Step-by-step guide for creating and deploying ODB database snapshots in production
author: epic-platform-sre
date_created: '2026-01-12'
last_updated: '2026-01-12'
tags: [how-to, odb, snapshot, backup, epic, azure]
category: database-operations
status: published
version: '1.0'
diataxis_type: how-to
---

Never generate partial front-matter or omit fields

3. Follow Filename Conventions

LLM-generated filenames MUST:

• Be lowercase: epic-odb-deployment.md
• Use hyphens: how-to-configure-awx.md
• Be descriptive: ansible-playbook-testing.md not testing.md
• Use index.md for section overviews

4. Review and Clean Old Content

When updating existing documentation:

1. Check last_updated field - If >1 year old, review carefully
2. Verify technical accuracy - Check versions, commands, screenshots
3. Update or deprecate - Don't leave outdated content

Example cleanup:

<!-- OLD (2023-06-15) -->

Install AWX 21.14:

```bash
pip install ansible-awx==21.14.0
```

<!-- UPDATED (2026-01-12) -->

🔄 Updated for AWX 22.x

Install AWX 22.0+ (current stable):

pip install ansible-awx>=22.0.0

Previous instructions for AWX 21.x have been archived.

#### 5. Use Proper Markdown Formatting

**Headings:**
- Use ATX-style: `## Heading` not `Heading\n========`
- Proper hierarchy: `# → ## → ###` (no skipping levels)

**Code Blocks:**
- Always specify language: ` ```python` not ` ``` `
- Include helpful comments
- Show complete, working examples

**Lists:**
- Use `-` for unordered lists (consistent across site)
- Use `1.` for ordered lists
- Indent nested lists with 2 spaces

**Links:**
- Use relative paths for internal links: `[Guide](../how-to/deploy.md)`
- Absolute URLs for external: `[Ansible Docs](https://docs.ansible.com)`

#### 6. Generate README.md vs index.md Correctly

**Repository root** (`/README.md`):
- Use uppercase `README.md`
- This is for GitHub display
- Contains project overview, setup, quick start

**Documentation index** (`/docs/index.md`):
- Use lowercase `index.md`
- This is for MkDocs site
- Contains documentation overview and navigation

**Don't confuse them or create both in same directory**

#### 7. Handle GitHub Documentation Files

**These files stay in repository root with UPPERCASE:**
- `README.md`
- `CONTRIBUTING.md`
- `CHANGELOG.md`
- `LICENSE.md`

**Never:**
- Rename to lowercase: ~~`readme.md`~~
- Move to `docs/`: ~~`docs/README.md`~~
- Create duplicates: ~~both `README.md` and `docs/readme.md`~~

#### 8. Context Awareness

**LLMs generating documentation MUST:**

✅ **Read existing documentation first** to understand:
- Current structure and organization
- Naming patterns used
- Existing content to avoid duplication
- Version/technology being documented

✅ **Check repository context**:
- Read `README.md` for project overview
- Check `mkdocs.yml` for navigation structure
- Understand if this is base repo or submodule

✅ **Follow repository conventions**:
- If repo uses `how-to/how-to-*.md` pattern, continue it
- If examples use specific code style, match it
- If diagrams are in `docs/assets/images/`, place new ones there

#### 9. Quality Checklist for LLM-Generated Docs

Before submitting documentation, verify:

- [ ] Correct Diataxis category (`tutorials`, `how-to`, `reference`, `explanation`)
- [ ] Complete YAML front-matter (all required fields)
- [ ] Lowercase filename with hyphens
- [ ] No spaces in filename
- [ ] Used `index.md` not `README.md` in `docs/`
- [ ] Specified language in all code blocks
- [ ] Included working, tested examples
- [ ] Added relevant images to `docs/assets/images/`
- [ ] Linked to related documentation
- [ ] Checked for outdated information
- [ ] Marked deprecated content appropriately
- [ ] Validated all links work
- [ ] Spell-checked content
- [ ] Reviewed for security concerns (no secrets, credentials)

## Examples

### ✅ CORRECT Example

**File**: `ohemr-ansible-playbooks/docs/how-to/how-to-deploy-odb-snapshot.md`

```markdown
---
title: How to Deploy Epic ODB Snapshot
description: Create and deploy ODB database snapshots for backup and disaster recovery
author: epic-platform-sre
date_created: '2026-01-12'
last_updated: '2026-01-12'
tags: [how-to, odb, snapshot, backup, azure, epic]
category: database-operations
status: published
version: '1.0'
diataxis_type: how-to
---

# How to Deploy Epic ODB Snapshot

This guide walks through creating and deploying an ODB (Operational Data Bank) snapshot for backup purposes.

## Prerequisites

- AWX access with `odb-operator` role
- Azure credentials for target subscription
- ODB instance name and resource group

## Step 1: Initiate Snapshot Job

Navigate to AWX and launch the **Epic ODB Snapshot** job template:

```bash
awx-cli job_templates launch \
  --name "Epic ODB Snapshot" \
  --extra_vars '{
    "odb_instance": "odb-prod-001",
    "retention_days": 30
  }'

[Rest of how-to guide...]

**Why this is correct:**
- ✅ In `how-to/` directory (task-oriented)
- ✅ Complete front-matter
- ✅ Lowercase filename with hyphens
- ✅ Clear, actionable steps
- ✅ Code examples with language specified

### ❌ INCORRECT Example

**File**: `ohemr-ansible-playbooks/docs/ODB Snapshot Guide.md`

```markdown
# ODB Snapshot Guide

Here's how to create snapshots...

[Content without front-matter, wrong location, spaces in filename]

Why this is wrong:

• ❌ Not in Diataxis directory structure
• ❌ No front-matter
• ❌ Spaces in filename
• ❌ Mixed case filename
• ❌ Ambiguous document type

Integration with otc-awesome-llm

Megadoc Custom Instructions

This instruction file is part of the otc-awesome-llm asset library and can be:

1. Applied to repositories via VS Code extension "Apply to Repo" feature
2. Referenced by MCP tools when generating documentation
3. Imported by LLM tools as context for documentation tasks
4. Enforced by CI/CD through validation checks

Automated Validation

# .github/workflows/docs-validation.yml
name: Documentation Validation
on: [pull_request]

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate front-matter
        run: |
          python scripts/validate-frontmatter.py

      - name: Check filename conventions
        run: |
          find docs/ -name "* *" && exit 1 || echo "No spaces in filenames"
          find docs/ -name "*[A-Z]*" -not -name "README.md" && exit 1 || echo "All lowercase"

      - name: Validate Diataxis structure
        run: |
          [[ -d docs/tutorials ]] && [[ -d docs/how-to ]] && [[ -d docs/reference ]]

Resources

• Diataxis Framework
• MkDocs Documentation
• Material for MkDocs
• ohemr-epic-megadoc Repository
• Markdown Guide

Maintenance

This instruction document is maintained by the Epic Platform SRE team. Questions or updates:

• Slack: #epic-platform-sre
• Email: [email protected]
• Issues: otc-awesome-llm Issues

Review Schedule: Quarterly (January, April, July, October)