Task

Perform comprehensive validation of megadoc-compliant documentation to ensure it meets all submodule requirements and quality standards before inclusion in ohemr-epic-megadoc.

Context

Documentation validation catches issues before they cause build failures or inconsistencies in the unified megadoc site. This validation ensures:

• Stub mkdocs.yml is correctly formatted
• All documentation has proper front matter
• Diátaxis framework is followed
• Style guide is adhered to
• Build succeeds locally
• No broken links

Instructions

Phase 1: Stub Configuration Validation

Check 1: File Existence

# Verify mkdocs.yml exists in repository root
ls mkdocs.yml

Expected: File exists If missing: ❌ CRITICAL - No mkdocs.yml found. Run megadoc-stub-generator to create.

Check 2: Required Fields

Read mkdocs.yml and verify presence of:

site_name: { value }
repo_url: { value }
repo_name: { value }
edit_uri: { value }

Validation:

• ✅ All four fields present
• ❌ Any field missing → CRITICAL

Check 3: Field Values

site_name:

• Should match repository name (consistency)
• Example: ohemr-terraform-module-vpc or VPC Terraform Module

repo_url:

• Must be full GitHub URL
• Format: https://github.com/{owner}/{repo}
• Example: https://github.com/optum-tech-compute/ohemr-terraform-module-vpc

repo_name:

• Must be {owner}/{repo} format
• Example: optum-tech-compute/ohemr-terraform-module-vpc
• Should match repo_url

edit_uri:

• Should be edit/{branch}/docs
• Common values: edit/main/docs, edit/develop/docs
• Must match actual default branch

Check 4: Forbidden Fields

MUST NOT be present in stub mkdocs.yml:

• theme:
• plugins:
• markdown_extensions:
• extra:
• extra_css:
• extra_javascript:

If found: ⚠️ WARNING - These fields are ignored; parent megadoc provides them. Remove to avoid confusion.

Check 5: Navigation Structure

Optional but recommended: nav: section

If present, validate:

• References actual files in docs/
• No broken references
• Logical organization
• Not too deep (max 3 levels recommended)

Example valid navigation:

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Reference:
      - API: reference/api.md
      - Configuration: reference/configuration.md

Check 6: YAML Syntax

# Validate YAML syntax
python -c "import yaml; yaml.safe_load(open('mkdocs.yml'))"

Expected: No errors If errors: ❌ CRITICAL - Fix YAML syntax errors

Phase 2: Documentation Structure Validation

Check 7: docs/ Folder Exists

ls docs/

Expected: docs/ directory exists If missing: ❌ CRITICAL - Create docs/ folder

Check 8: docs/index.md Exists

ls docs/index.md

Expected: Landing page exists If missing: ❌ CRITICAL - docs/index.md is required

Check 9: Directory Organization

Recommended structure (validate if present):

docs/
├── index.md                    # Required
├── getting-started.md          # Recommended
├── how-to/                     # Task-oriented guides
│   └── *.md
├── reference/                  # Information-oriented docs
│   └── *.md
├── runbooks/                   # Operational procedures
│   └── *.md
└── concepts/ or *.md           # Understanding-oriented docs

Diátaxis compliance:

• ✅ Good: Clear separation between doc types
• ⚠️ Warning: All docs in root (consider organizing)
• ❌ Bad: Inconsistent naming (some lowercase, some camelCase)

Phase 3: Front Matter Validation

For every markdown file in docs/:

Check 10: Front Matter Presence

---
{ front matter }
---

# Content

Validation:

• File starts with ---
• YAML front matter block
• Closes with ---
• Content follows

If missing: ❌ CRITICAL - Front matter required on all docs

Check 11: Required Front Matter Fields

Must be present:

title: { value }
description: { value }
owner: { value }
doc_type: { value }
lifecycle_status: { value }
last_reviewed: { value }
tags: { array }

Validation checklist:

• title - Present and non-empty
• description - Present and non-empty (one sentence)
• owner - Present (team name or GitHub username)
• doc_type - Present and valid value
• lifecycle_status - Present and valid value
• last_reviewed - Present and valid date format
• tags - Present and array with at least one tag

Check 12: Field Value Validation

doc_type - Must be one of:

• how-to - Task-oriented guides
• reference - Information lookups
• runbook - Operational procedures
• concept - Understanding-oriented

If invalid: ❌ ERROR - Use valid doc_type

lifecycle_status - Must be one of:

• active - Current and maintained
• experimental - New, subject to change
• deprecated - Being phased out

If invalid: ❌ ERROR - Use valid lifecycle_status

last_reviewed - Must be date format:

• Format: YYYY-MM-DD
• Example: 2025-12-18
• Should be recent (warn if >6 months old)

If invalid: ❌ ERROR - Use YYYY-MM-DD format

tags - Must be array:

tags:
  - tag1
  - tag2

Not:

tags: tag1, tag2 # Wrong

Check 13: Front Matter YAML Syntax

# Validate front matter YAML
import yaml
try:
    yaml.safe_load(front_matter_content)
    print("✅ Valid YAML")
except yaml.YAMLError as e:
    print(f"❌ YAML syntax error: {e}")

Phase 4: Content Validation

Check 14: Heading Style

Rule: Use sentence case for headings

✅ Good:

# Getting started

## Installation steps

❌ Bad:

# Getting Started

## Installation Steps

Scan all headings and report non-sentence-case headings as warnings.

Check 15: Code Block Annotation

Rule: All code blocks must specify language

✅ Good:

```yaml
key: value
```

command --option value

❌ Bad:

key: value

**Scan for unannotated code blocks** and report as warnings.

### Check 16: Link Format

**Rule**: Prefer relative links

```markdown
✅ Good:
[Configuration](./reference/configuration.md)
[API Docs](../api/index.md)

❌ Bad:
[Configuration](/docs/reference/configuration.md)
[API Docs](https://docs.epic.optum.com/repo/api/)

Validation:

• Identify absolute paths starting with /docs/
• Warn about potential issues in submodule context

Check 17: Broken Links

Test all internal markdown links:

1. Extract all markdown links: [text](path.md)
2. Resolve relative paths
3. Check if target files exist
4. Report broken links as errors

# Pseudo-code
for link in markdown_links:
    if not exists(resolve_path(link)):
        print(f"❌ Broken link: {link}")

Check 18: Admonition Syntax

Rule: Use Material theme admonition syntax

✅ Good:
!!! note
Content here

!!! warning
Important warning

❌ Bad:

> **Note**: Content here
> **Warning**: Important warning

Validation: Scan for old-style callouts and suggest conversion.

Phase 5: Build Validation

Check 19: Local Build Test

# Install dependencies
pip install mkdocs mkdocs-material

# Build documentation
mkdocs build --strict

Expected: Build succeeds with no errors If errors: ❌ CRITICAL - Fix build errors before proceeding

Common errors:

• File not found in navigation
• Invalid YAML in mkdocs.yml
• Broken internal links
• Missing front matter breaking plugins

Check 20: Serve Test

# Serve locally
mkdocs serve

Manual checks:

• Visit http://localhost:8000
• Verify navigation appears correctly
• Check pages render properly
• Test search functionality
• Verify code blocks have syntax highlighting
• Check "Edit on GitHub" links work

Phase 6: Integration Readiness

Check 21: Repository Context

Verify repository is ready for megadoc inclusion:

Git configuration:

# Check remote URL
git remote get-url origin
# Should be: https://github.com/optum-tech-compute/{repo}

# Check default branch
git symbolic-ref refs/remotes/origin/HEAD
# Should match edit_uri in mkdocs.yml

Check 22: Megadoc Inclusion Test

Simulate inclusion:

1. Clone ohemr-epic-megadoc
2. Add repository as submodule (or use existing)
3. Add !include to parent mkdocs.yml
4. Build megadoc site
5. Verify documentation appears correctly

# In megadoc mkdocs.yml
nav:
  - Test:
      - My Repo: '!include submodules/my-repo/mkdocs.yml'

cd /path/to/ohemr-epic-megadoc
mkdocs build

Expected: Build succeeds, navigation includes your docs

Validation Report

Generate comprehensive report:

# Megadoc Documentation Validation Report

**Repository**: {repo-name}
**Validated**: {timestamp}
**Status**: {PASS|FAIL}

## Summary

- ✅ Passed: {count} checks
- ❌ Failed: {count} checks
- ⚠️ Warnings: {count} checks

## Critical Issues

{List of critical failures that must be fixed}

## Errors

{List of errors that should be fixed}

## Warnings

{List of warnings (non-blocking but recommended)}

## Validation Details

### Configuration

- ✅ mkdocs.yml exists
- ✅ Required fields present
- ✅ No forbidden fields
- ✅ YAML syntax valid

### Structure

- ✅ docs/ folder exists
- ✅ docs/index.md present
- ✅ Diátaxis organization followed

### Front Matter

- ✅ All files have front matter
- ✅ Required fields present
- ✅ Valid doc_type values
- ⚠️ 2 files have old last_reviewed dates

### Content

- ✅ Heading style consistent
- ✅ Code blocks annotated
- ⚠️ 3 absolute links found
- ✅ No broken links

### Build

- ✅ Local build succeeds
- ✅ Site renders correctly
- ✅ Navigation structure correct

## Recommendations

1. {Specific improvement recommendations}
2. {Areas for enhancement}
3. {Documentation gaps to fill}

## Next Steps

{If PASS}:
✅ Documentation is megadoc-compliant!

Ready for inclusion in ohemr-epic-megadoc:

1. Commit and push changes
2. Request submodule addition
3. Provide megadoc team with repo URL

{If FAIL}:
❌ Fix critical issues before proceeding:

1. {Issue 1}
2. {Issue 2}

Then re-run validation.

Guidelines

Severity Levels

❌ CRITICAL: Prevents megadoc inclusion or breaks build

• Missing mkdocs.yml
• Missing docs/index.md
• Build failures
• Broken links in navigation

❌ ERROR: Violates standards but doesn't break build

• Missing front matter fields
• Invalid field values
• Broken internal links
• YAML syntax errors

⚠️ WARNING: Recommendations for improvement

• Old last_reviewed dates
• Non-sentence-case headings
• Absolute links
• Unannotated code blocks
• Forbidden fields in stub (ignored but confusing)

Validation Modes

Quick validation (pre-commit):

• Configuration validation
• Front matter presence
• YAML syntax

Full validation (pre-merge):

• All checks
• Build test
• Link validation
• Content quality

Integration validation (before megadoc inclusion):

• Full validation
• Megadoc inclusion test
• Multi-repo build test

Expected Output

Success Case

✅ **Megadoc Validation: PASS**

All checks passed! Documentation is ready for megadoc inclusion.

**Summary:**

- Configuration: ✅ Valid
- Structure: ✅ Compliant
- Front Matter: ✅ Complete
- Content: ✅ High quality
- Build: ✅ Success

**Next Steps:**

1. Commit changes
2. Request megadoc inclusion
3. Provide repo URL to @epic-platform-sre

Failure Case

❌ **Megadoc Validation: FAIL**

Found 3 critical issues and 5 warnings.

**Critical Issues:**

1. ❌ Missing docs/index.md
2. ❌ mkdocs.yml missing repo_url field
3. ❌ Build fails due to broken navigation link

**Fix These Issues:**

1. Create docs/index.md with proper front matter
2. Add repo_url to mkdocs.yml
3. Fix navigation link: getting-started.md → getting-started.md

**Warnings:**

1. ⚠️ 5 files have old last_reviewed dates (>6 months)
2. ⚠️ 3 headings use title case instead of sentence case
3. ⚠️ 2 code blocks missing language annotation

Re-run validation after fixes.

Notes

• Run validation before requesting megadoc inclusion
• Fix critical issues first, then errors, then warnings
• Re-validate after making changes
• Contact @epic-platform-sre if validation guidance is unclear