Task

Generate megadoc-compliant documentation structure for this repository including stub mkdocs.yml and initial docs/ folder with proper front matter.

Mandatory Requirements

Requirement	Rule	Rationale
Stub Only	MUST include only metadata in mkdocs.yml (site_name, repo_url, repo_name, edit_uri)	Parent megadoc provides plugins/themes
No Plugins	MUST NOT add plugins, themes, or extensions to stub mkdocs.yml	Prevents conflicts with parent
Front Matter	MUST include YAML front matter on every markdown file	Megadoc metadata requirements
Index Required	MUST create docs/index.md as landing page	Navigation entry point
Diátaxis Structure	MUST organize content using Diátaxis framework	Consistent documentation architecture

Prohibited Patterns

Pattern	Prohibition	Alternative
Full mkdocs.yml	NEVER copy full mkdocs.yml config from another project	Use stub template only
Theme Config	NEVER add theme configuration to submodule mkdocs.yml	Parent provides theme
Plugin Config	NEVER add plugins to submodule mkdocs.yml	Parent provides plugins
Missing Front Matter	NEVER create markdown without YAML front matter	Add frontmatter to all .md files
Absolute Links	NEVER use absolute URLs for internal documentation links	Use relative paths only

Context

This repository will be included as a Git submodule in the ohemr-epic-megadoc monorepo. The documentation must follow megadoc submodule patterns:

• Stub mkdocs.yml with only metadata (site_name, repo_url, repo_name, edit_uri)
• No plugins, themes, or extensions in stub (parent megadoc provides these)
• Front matter on every markdown file
• Diátaxis framework organization

Instructions

Step 1: Repository Analysis

Analyze the repository to determine:

1. Repository details:

   • Owner/organization: optum-tech-compute
   • Repository name: [Detect from git config or ask]
   • Default branch: [Usually main or develop]

2. Repository type (determines documentation structure):

   • Terraform module
   • Ansible role
   • GitHub Action
   • Python package
   • Application/service
   • Library
   • Documentation site

3. Key content to document:

   • What does this repository do?
   • What are the main features?
   • What do users need to know?

Step 2: Create mkdocs.yml Stub

Create mkdocs.yml in repository root:

site_name: {repository-name}
repo_url: https://github.com/optum-tech-compute/{repository-name}
repo_name: optum-tech-compute/{repository-name}
edit_uri: edit/main/docs

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - {Category}: {category}/

Customization:

• Replace {repository-name} with actual repository name
• Adjust edit_uri if default branch is not main
• Define navigation based on repository type (see templates below)

Step 3: Create docs/ Structure

Create docs/ folder with initial files:

docs/index.md (Required)

---
title: { Repository Name }
description: { One-sentence description of what this repository does }
owner: { team-name or github-username }
doc_type: concept
lifecycle_status: active
last_reviewed: { today's date YYYY-MM-DD }
tags:
  - { tag1 }
  - { tag2 }
  - { tag3 }
---

# {Repository Name}

{Brief overview paragraph}

## Overview

{Detailed description of what this repository provides}

## Quick Start

{Minimal example to get started}

## Features

- Feature 1
- Feature 2
- Feature 3

## Documentation

- [Getting Started](getting-started.md) - Installation and setup
- [Configuration Reference](reference/configuration.md) - Configuration options
- [{Type-specific docs}](...)

## Support

- **Issues**: [GitHub Issues](https://github.com/optum-tech-compute/{repository-name}/issues)
- **Discussions**: [GitHub Discussions](https://github.com/optum-tech-compute/{repository-name}/discussions)
- **Owner**: {team-name}

docs/getting-started.md

---
title: Getting Started with {Repository Name}
description: Installation, setup, and first steps for {repository name}
owner: { team-name }
doc_type: how-to
lifecycle_status: active
last_reviewed: { today }
tags:
  - getting-started
  - installation
  - setup
---

# Getting Started

## Prerequisites

- Prerequisite 1
- Prerequisite 2
- Prerequisite 3

## Installation

{Installation steps based on repository type}

## Basic Usage

{Simple example demonstrating core functionality}

## Next Steps

- [{Advanced topic}](how-to/{topic}.md)
- [Configuration Reference](reference/configuration.md)
- [{Type-specific next step}](...)

Step 4: Type-Specific Templates

For Terraform Modules

Navigation:

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - How-To Guides:
      - Deploy Module: how-to/deploy.md
      - Configure Options: how-to/configure.md
  - Reference:
      - Inputs: reference/inputs.md
      - Outputs: reference/outputs.md
      - Resources: reference/resources.md
  - Examples: examples.md

docs/reference/inputs.md:

---
title: Input Variables
description: All input variables accepted by this Terraform module
owner: { team }
doc_type: reference
lifecycle_status: active
last_reviewed: { today }
tags:
  - terraform
  - inputs
  - variables
  - reference
---

# Input Variables

## Required Variables

### `variable_name`

- **Type**: `string`
- **Description**: {Description}
- **Example**: `"example-value"`

## Optional Variables

### `optional_var`

- **Type**: `string`
- **Default**: `"default-value"`
- **Description**: {Description}

For Ansible Roles

Navigation:

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - How-To Guides:
      - Apply Role: how-to/apply-role.md
      - Customize Variables: how-to/customize.md
  - Reference:
      - Variables: reference/variables.md
      - Tags: reference/tags.md
      - Handlers: reference/handlers.md
  - Examples: examples.md

docs/reference/variables.md:

---
title: Role Variables
description: All variables available for this Ansible role
owner: { team }
doc_type: reference
lifecycle_status: active
last_reviewed: { today }
tags:
  - ansible
  - variables
  - reference
---

# Role Variables

## Required Variables

### `var_name`

- **Type**: string
- **Description**: {Description}
- **Example**: `"example-value"`

## Optional Variables

### `optional_var`

- **Type**: string
- **Default**: `"default"`
- **Description**: {Description}

For GitHub Actions

Navigation:

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - How-To Guides:
      - Use in Workflow: how-to/use-action.md
      - Configure Options: how-to/configure.md
  - Reference:
      - Inputs: reference/inputs.md
      - Outputs: reference/outputs.md
  - Examples: examples.md

For Python Packages

Navigation:

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - How-To Guides:
      - Installation: how-to/install.md
      - Basic Usage: how-to/basic-usage.md
  - Reference:
      - API Reference: reference/api.md
      - Configuration: reference/configuration.md
  - Examples: examples.md

For Applications/Services

Navigation:

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Architecture: architecture.md
  - How-To Guides:
      - Deploy: how-to/deploy.md
      - Configure: how-to/configure.md
      - Monitor: how-to/monitor.md
  - Reference:
      - API: reference/api.md
      - Configuration: reference/configuration.md
  - Runbooks:
      - Incident Response: runbooks/incident-response.md
      - Maintenance: runbooks/maintenance.md

Step 5: Additional Files

.gitignore (if not present)

# MkDocs
site/
.cache/

README.md Update

Add documentation badge and link:

## Documentation

📚 [Full Documentation](https://docs.epic.optum.com/{repository-path})

- [Getting Started](docs/getting-started.md)
- [Configuration Reference](docs/reference/configuration.md)
- [Examples](docs/examples.md)

## Building Documentation Locally

```bash
pip install mkdocs mkdocs-material
mkdocs serve
```

Visit http://localhost:8000

## Step 6: Validation

Before completing:

1. **Validate mkdocs.yml syntax**:
   ```bash
   python -c "import yaml; yaml.safe_load(open('mkdocs.yml'))"

1. Test build locally:

   mkdocs build
   

2. Check front matter:

   • All .md files have front matter
   • Required fields present (title, description, owner, doc_type, lifecycle_status, last_reviewed, tags)
   • No YAML syntax errors

3. Verify links:

   • All internal links use relative paths
   • Navigation items reference existing files
   • No broken links

Step 7: Output Summary

Provide summary of what was created:

✅ Megadoc documentation structure created!

**Files Created:**

- `mkdocs.yml` - Stub configuration
- `docs/index.md` - Landing page
- `docs/getting-started.md` - Getting started guide
- `docs/reference/` - Reference documentation
- `docs/how-to/` - How-to guides
- [Other files based on type]

**Next Steps:**

1. Review and customize the generated content
2. Add repository-specific details
3. Test locally: `mkdocs serve`
4. Commit and push to repository
5. Request inclusion in ohemr-epic-megadoc

**Megadoc Integration:**
Your repository can be included in megadoc with:

```yaml
- { Repository }: '!include submodules/{repository-name}/mkdocs.yml'
```

# Guidelines

## Front Matter Requirements

**Every markdown file must include**:
```yaml
---
title: {Page Title}
description: {One-sentence description}
owner: {team-name or github-username}
doc_type: {how-to|reference|runbook|concept}
lifecycle_status: {active|experimental|deprecated}
last_reviewed: {YYYY-MM-DD}
tags:
  - {relevant}
  - {tags}
---

Diátaxis Categories

• how-to: Task-oriented guides ("How to deploy", "How to configure")
• reference: Information lookups (API docs, configuration options, schemas)
• runbook: Operational procedures (incident response, maintenance)
• concept: Understanding-oriented (architecture, design principles)

Style Guide

• Headings: Sentence case ("Getting started" not "Getting Started")
• Code blocks: Always annotate language (yaml,bash, ```python)
• Links: Use relative paths (./reference/config.md not /docs/reference/config.md)
• Lists: Parallel structure
• Admonitions: Use Material theme syntax (!!! note, !!! warning, !!! tip)

What NOT to Include in Stub

DO NOT add to mkdocs.yml:

• theme: - Parent provides theme
• plugins: - Parent provides plugins
• markdown_extensions: - Parent provides extensions
• extra: - Parent provides extras
• extra_css: - Managed centrally
• extra_javascript: - Managed centrally

Expected Output

Created files:

1. mkdocs.yml - Minimal stub configuration
2. docs/index.md - Landing page with overview
3. docs/getting-started.md - Getting started guide
4. Type-specific reference/how-to/runbook documentation
5. Updated README.md with documentation link

Validation:

• ✅ mkdocs.yml has only required fields
• ✅ All markdown files have front matter
• ✅ Navigation references existing files
• ✅ Local build succeeds (mkdocs build)
• ✅ No broken internal links
• ✅ Style guide followed

Notes

• This scaffold provides starting structure; customize based on repository specifics
• Fill in placeholder content with actual repository details
• Test locally before committing
• Request megadoc inclusion after documentation is ready