Task

Create high-quality, megadoc-compliant documentation content following Diátaxis framework, style guide standards, and front matter requirements.

Context

Use this prompt when you need to:

• Create new documentation pages
• Convert existing content to megadoc format
• Fill documentation gaps
• Generate specific doc types (how-to, reference, runbook, concept)

Instructions

Step 1: Understand the Documentation Need

Gather context:

• What needs to be documented?
• Who is the target audience?
• What do users need to accomplish or understand?
• What is the appropriate Diátaxis category?

Determine doc type:

• how-to: Task-oriented (user wants to accomplish a goal)
• reference: Information-oriented (user needs to look up details)
• runbook: Procedural (operational tasks and incident response)
• concept: Understanding-oriented (user wants to learn about architecture/design)

Step 2: Create Front Matter

Generate appropriate YAML front matter:

---
title: { Clear, descriptive title }
description: { One-sentence summary of page content }
owner: { team-name or github-username }
doc_type: { how-to|reference|runbook|concept }
lifecycle_status: { active|experimental|deprecated }
last_reviewed: { today's date YYYY-MM-DD }
tags:
  - { relevant-tag-1 }
  - { relevant-tag-2 }
  - { relevant-tag-3 }
---

Front matter guidelines:

title:

• Sentence case ("Getting started" not "Getting Started")
• Clear and specific
• Matches file name semantically
• Examples:
  • "Deploy application with Terraform"
  • "API endpoint reference"
  • "Incident response runbook"

description:

• One concise sentence
• Describes what reader will learn/accomplish
• Used in search results and navigation hints
• Examples:
  • "Step-by-step guide for deploying the application using Terraform"
  • "Complete reference for all REST API endpoints"
  • "Procedures for responding to production incidents"

owner:

• Team name (epic-platform-sre) or GitHub username
• Responsible for maintaining this documentation
• Contact point for questions

doc_type:

• Must be valid value: how-to, reference, runbook, concept
• Determines page organization and presentation
• Should match Diátaxis categorization

lifecycle_status:

• active: Current, maintained, production-ready
• experimental: New, subject to change, use with caution
• deprecated: Being phased out, use alternatives

last_reviewed:

• Today's date in YYYY-MM-DD format
• Indicates content freshness
• Should be updated during content reviews

tags:

• 3-5 relevant tags
• Improve searchability
• Use existing tag vocabulary when possible
• Examples: terraform, deployment, api, aws, kubernetes, python

Step 3: Create Content by Doc Type

How-To Guide Template

---
title: { Task to accomplish }
description: { What user will accomplish }
owner: { team }
doc_type: how-to
lifecycle_status: active
last_reviewed: { today }
tags:
  - how-to
  - { domain }
  - { technology }
---

# {Task to Accomplish}

{Brief introduction: what this guide covers and why}

## Prerequisites

Before you begin, ensure you have:

- Prerequisite 1
- Prerequisite 2
- Prerequisite 3

## Steps

### 1. {First major step}

{Detailed instructions for first step}

```{language}
{code example}
```

{Explanation of what this code does}

2. {Second major step}

{Detailed instructions}

{code example}

3. {Third major step}

{Continue as needed}

Verification

Verify the setup works correctly:

{verification command}

Expected output:

{expected output}

Troubleshooting

Issue: {Common problem}

Symptom: {How user notices this} Solution: {How to fix}

Issue: {Another common problem}

Symptom: {How it manifests} Solution: {Resolution steps}

Next steps

• {Related how-to}
• {Advanced topic}
• {Reference docs}

### Reference Documentation Template

```markdown
---
title: {Component/API/Config reference}
description: {What this reference covers}
owner: {team}
doc_type: reference
lifecycle_status: active
last_reviewed: {today}
tags:
  - reference
  - {component}
  - {domain}
---

# {Component Name} Reference

{Brief overview of what this reference documents}

## {Section 1 - e.g., Configuration Options}

### `option_name`

- **Type**: `string` | `number` | `boolean` | `array` | `object`
- **Required**: Yes | No
- **Default**: `default-value` or "none"
- **Description**: {What this option does and when to use it}
- **Example**:
  ```{language}
  option_name: example-value

• Constraints: {Any limits, validation rules, or dependencies}

another_option

{Repeat structure for each option}

{Section 2 - e.g., API Endpoints}

GET /api/resource

Description: {What this endpoint does}

Request:

GET /api/resource?param1=value1 HTTP/1.1
Authorization: Bearer {token}

Parameters:

• param1 (string, optional): {Description}
• param2 (number, required): {Description}

Response (200 OK):

{
  "key": "value",
  "data": []
}

Response Fields:

• key (string): {Description}
• data (array): {Description}

Error Responses:

• 400 Bad Request: {When this occurs}
• 401 Unauthorized: {When this occurs}
• 404 Not Found: {When this occurs}

Example:

curl -X GET "https://api.example.com/resource?param1=value1" \
  -H "Authorization: Bearer <YOUR_TOKEN_HERE>"

{Section 3 - e.g., Data Models}

ModelName

{Description of this data model}

Fields:

• field1 (string, required): {Description}
• field2 (number, optional): {Description}
• field3 (object): {Description}
  • nested1 (string): {Description}

Example:

{
  "field1": "value",
  "field2": 42,
  "field3": {
    "nested1": "nested-value"
  }
}

Related Documentation

• How-to guide
• Architecture overview

### Runbook Template

```markdown
---
title: {Procedure name} runbook
description: {What operational task this runbook covers}
owner: {team}
doc_type: runbook
lifecycle_status: active
last_reviewed: {today}
tags:
  - runbook
  - operations
  - {system}
---

# {Procedure Name} Runbook

## Overview

**Purpose**: {What this runbook helps you accomplish}
**Audience**: {Who should use this runbook}
**Frequency**: {How often this procedure is performed}

## When to Use This Runbook

Use this runbook when:
- Trigger condition 1
- Trigger condition 2
- Trigger condition 3

## Prerequisites

- Access requirement 1
- Tool requirement 2
- Knowledge requirement 3

## Diagnosis

### Step 1: Check {System Component}

```bash
{diagnostic command}

Expected output:

{normal output}

If output differs: {What this means}

Step 2: Verify {Another Component}

{Additional diagnostic steps}

Resolution Procedure

Standard Resolution

Step 1: {First action}

{command}

Expected result: {What should happen}

Step 2: {Second action}

{command}

Step 3: {Continue as needed}

Alternative Resolution (If Standard Fails)

{Alternative approach if standard resolution doesn't work}

Verification

Confirm the issue is resolved:

1. {Verification step 1}

   {verification command}
   

2. {Verification step 2}

Escalation

If resolution fails after attempting all procedures:

Contact: {Team/person to contact} Channel: {Slack channel, email, on-call} Information to provide:

• Issue description
• Diagnostic output
• Resolution steps attempted
• Current system state

Post-Incident

After resolving the incident:

• Document incident in {tracking system}
• Update monitoring/alerting if needed
• Review and update this runbook if procedures changed
• Conduct post-mortem if major incident

Related Runbooks

• {Related runbook 1}
• {Related runbook 2}

### Concept Documentation Template

```markdown
---
title: {Concept or system name}
description: {High-level description of concept}
owner: {team}
doc_type: concept
lifecycle_status: active
last_reviewed: {today}
tags:
  - concept
  - architecture
  - {domain}
---

# {Concept or System Name}

{Opening paragraph: What is this concept/system and why does it exist?}

## Overview

{High-level explanation of the concept, avoiding implementation details}

## Key Concepts

### {Concept 1}

{Explanation of first key concept}

### {Concept 2}

{Explanation of second key concept}

## Architecture

{Describe the overall architecture, structure, or design}

### Components

**{Component 1}**:
- Purpose: {Why this component exists}
- Responsibility: {What it does}
- Interfaces: {How it connects to other components}

**{Component 2}**:
{Repeat for each component}

### Data Flow

{Explain how data/requests flow through the system}

```mermaid
graph LR
    A[Component A] -->|Data| B[Component B]
    B -->|Result| C[Component C]

Design Decisions

Decision: {Design decision 1}

Rationale: {Why this decision was made} Alternatives considered: {What else was considered} Trade-offs: {What was gained/lost}

Use Cases

Use Case 1: {Scenario}

{Describe how the system handles this scenario}

Use Case 2: {Another scenario}

{Describe this scenario}

Constraints and Limitations

• Constraint 1: {Description and implications}
• Constraint 2: {Description and implications}

Related Documentation

• How-to guide - Learn how to use this system
• API Reference - Technical specifications
• Deployment Guide - How to deploy

## Step 4: Apply Style Guide

**Headings**:
- Use sentence case: "Getting started" not "Getting Started"
- Keep concise and specific
- Maximum 3 levels deep

**Code blocks**:
- Always annotate language: ```yaml, ```bash, ```python
- Include comments explaining non-obvious code
- Show actual runnable examples

**Links**:
- Use relative paths: `./reference/config.md`
- Not absolute paths: `/docs/reference/config.md`
- Link to related documentation

**Lists**:
- Use parallel structure
- Start with verb for action items
- Be consistent in formatting

**Admonitions**:
```markdown
!!! note
    Informational callout

!!! warning
    Important caution

!!! danger
    Critical warning

!!! tip
    Helpful suggestion

!!! example
    Code example or demonstration

Step 5: Add Value

Make it useful:

• Include practical examples
• Anticipate common questions
• Link to related resources
• Explain the "why" not just the "what"

Make it findable:

• Use descriptive titles
• Add relevant tags
• Link from other docs
• Include in navigation

Make it maintainable:

• Keep content focused
• Avoid duplication
• Update last_reviewed dates
• Mark deprecated content

Step 6: Validate

Before finalizing:

• Front matter complete and valid
• Correct doc_type for Diátaxis category
• Style guide followed (sentence case, annotated code, relative links)
• Code examples syntactically correct
• Links work (no broken references)
• Grammar and spelling checked
• Technical accuracy verified

Common Patterns

Converting Existing Documentation

If converting from non-megadoc format:

1. Add front matter (may not exist)
2. Determine correct Diátaxis category
3. Reorganize content to match template
4. Update links to relative paths
5. Annotate code blocks
6. Fix heading case
7. Add admonitions for callouts

Filling Documentation Gaps

If documentation is completely missing:

1. Analyze what needs documentation (code, config, API, etc.)
2. Choose appropriate doc type
3. Start with template for that type
4. Fill in content based on code/system
5. Add examples from actual usage
6. Test examples for correctness
7. Link from related documentation

Multi-Page Documentation

If topic requires multiple pages:

1. Create index page (concept) explaining overall topic
2. Create separate how-to guides for each task
3. Create reference page for technical details
4. Create runbooks for operational procedures
5. Link pages together
6. Add all to navigation

Expected Output

Complete Documentation Page

File: docs/{category}/{descriptive-name}.md

Content:

• Valid YAML front matter with all required fields
• Diátaxis-appropriate structure and content
• Style guide compliance
• Working code examples
• Relative links
• Clear, accurate, helpful information

Example:

---
title: Deploy application to Kubernetes
description: Step-by-step guide for deploying the application to a Kubernetes cluster
owner: platform-team
doc_type: how-to
lifecycle_status: active
last_reviewed: 2025-12-18
tags:
  - kubernetes
  - deployment
  - how-to
---

# Deploy application to Kubernetes

This guide walks you through deploying the application to a Kubernetes cluster using Helm.

## Prerequisites

Before you begin, ensure you have:

- Kubernetes cluster (v1.24 or later)
- `kubectl` configured for your cluster
- Helm 3.x installed
- Access to the application container registry

## Steps

### 1. Add the Helm repository

```bash
helm repo add myapp https://charts.example.com/myapp
helm repo update
```

2. Create namespace

kubectl create namespace myapp-prod

3. Deploy with Helm

helm install myapp myapp/application \
  --namespace myapp-prod \
  --set image.tag=v1.2.3 \
  --set replicas=3

4. Verify deployment

kubectl get pods -n myapp-prod

Expected output:

NAME                     READY   STATUS    RESTARTS   AGE
myapp-5d6f8c9b-7x2pl    1/1     Running   0          30s
myapp-5d6f8c9b-9k4mn    1/1     Running   0          30s
myapp-5d6f8c9b-qr8tz    1/1     Running   0          30s

Troubleshooting

Issue: Pods stuck in ImagePullBackOff

Symptom: Pods show ImagePullBackOff status Solution: Verify image tag and registry access

kubectl describe pod -n myapp-prod {pod-name}

Next steps

• Configure application
• Monitor application
• Kubernetes configuration reference

# Notes

- Choose appropriate doc type based on user need
- Follow templates but adapt to specific content
- Include practical, tested examples
- Keep content focused and maintainable
- Link to related documentation
- Update last_reviewed during reviews