Megadoc Documentation Style Guide

Overview

Megadoc is our documentation system for generating consolidated, searchable documentation from markdown files with YAML front matter. This guide covers required structure, formatting conventions, and best practices.

Required Front Matter

MUST include YAML front matter in every markdown file:

---
title: Document Title
description: >-
  A clear, concise description of the document's purpose
  (1-2 sentences, used for search and previews)
owner: team-name-or-individual
lifecycle_status: experimental | stable | deprecated
last_reviewed: '2024-12-19'
tags:
  - relevant
  - topic
  - tags
---

Front Matter Fields

Field	Required	Description
title	Yes	Document title (sentence case)
description	Yes	1-2 sentence summary for search/previews
owner	Yes	Team or individual responsible
lifecycle_status	Yes	experimental, stable, or deprecated
last_reviewed	Yes	ISO date of last review (YYYY-MM-DD)
tags	Yes	Array of relevant topic tags

Optional Front Matter

---
# ... required fields ...

# Optional fields
source_system: originating-system
source_url: https://source-system/path
related_docs:
  - path/to/related-doc.md
  - path/to/another-doc.md
audience:
  - developers
  - operators
  - architects
difficulty: beginner | intermediate | advanced
---

Diátaxis Framework

MUST categorize documentation using Diátaxis prefixes:

Document Types

Prefix	Type	Purpose	Example Titles
how-to-	How-To Guide	Step-by-step task completion	how-to-deploy-to-aks.md
concept-	Explanation	Understanding concepts	concept-kubernetes-networking.md
ref-	Reference	Technical specifications	ref-api-endpoints.md
runbook-	Runbook	Operational procedures	runbook-database-failover.md
adr-YYYYMMDD-	ADR	Architecture Decision Record	adr-20241219-use-managed-identity.md

When to Use Each Type

How-To Guides (how-to-):

• Task-oriented, goal-focused
• Assumes reader knows what they want to accomplish
• Example: "How to configure alerting for your service"

---
title: How to Configure Service Alerting
description: Step-by-step guide to set up monitoring alerts for your service
---

# How to Configure Service Alerting

## Prerequisites

- Access to Azure portal
- Service already deployed to AKS

## Steps

### Step 1: Access the monitoring dashboard

Navigate to the Azure portal and select your resource group...

Explanations (concept-):

• Understanding-oriented
• Explains why things work the way they do
• Example: "Understanding our logging architecture"

---
title: Understanding the Logging Architecture
description: Explains how logs flow from services to our analytics platform
---

# Understanding the Logging Architecture

## Overview

Our logging architecture follows a hub-and-spoke model where...

## Key Components

### Log Collection

Applications emit structured logs using...

### Log Aggregation

Logs are collected by Fluent Bit and forwarded to...

References (ref-):

• Information-oriented
• Accurate, complete technical details
• Example: "API endpoint reference"

---
title: Platform API Reference
description: Complete reference of platform API endpoints and parameters
---

# Platform API Reference

## Authentication

All endpoints require Bearer token authentication.

## Endpoints

### GET /api/v1/services

Returns a list of all registered services.

**Parameters:**

| Name   | Type    | Required | Description                    |
| ------ | ------- | -------- | ------------------------------ |
| limit  | integer | No       | Maximum results (default: 100) |
| offset | integer | No       | Pagination offset              |

**Response:**

```json
{
  "services": [...],
  "total": 42
}
```

**Runbooks** (`runbook-`):
- Operational procedures for incidents
- Step-by-step with decision points
- Example: "Database failover runbook"

```markdown
---
title: Database Failover Runbook
description: Procedure for failing over the primary database
---

# Database Failover Runbook

## When to Use
- Primary database unresponsive for > 5 minutes
- Planned maintenance requiring failover

## Prerequisites
- [ ] Confirm you have DBA permissions
- [ ] Notify #platform-ops channel

## Procedure

### 1. Assess Current State

```bash
az sql db show --name $DB_NAME --server $SERVER_NAME

Expected output: State should show "Online" or "Pausing"

If state is "Unknown": Proceed to step 2 If state is "Online": Verify connectivity issues first

2. Initiate Failover

...

## Heading Structure

### Hierarchy Rules

**MUST** follow heading hierarchy:

```markdown
# Document Title (H1 - only one per document)

## Major Section (H2)

### Subsection (H3)

#### Minor Point (H4)

NEVER skip heading levels:

# Title

### Wrong - skipped H2 ❌

## Correct - H2 follows H1 ✅

### Then H3 follows H2 ✅

Heading Style

MUST use sentence case for headings:

## How to configure monitoring ✅

## How To Configure Monitoring ❌

## HOW TO CONFIGURE MONITORING ❌

Code Blocks

Language Annotation

MUST annotate code blocks with language:

```bash
kubectl get pods -n production
```

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
```

```python
def process_event(event: dict) -> None:
    """Process an incoming event."""
    pass
```

```hcl
resource "azurerm_resource_group" "main" {
  name     = "rg-platform"
  location = "eastus2"
}
```

```json
{
  "name": "example",
  "version": "1.0.0"
}
```

Supported Languages

Language	Annotation	Use For
bash	bash	Shell commands, scripts
yaml	yaml	Kubernetes manifests, config files
json	json	API responses, package.json
python	python	Python code
javascript	javascript	JS/Node.js code
typescript	typescript	TypeScript code
hcl	hcl	Terraform configurations
sql	sql	Database queries
markdown	markdown	Nested markdown examples

Lists and Tables

List Formatting

PREFER bullet lists for unordered items:

Key features:

- Automatic scaling
- Self-healing
- Rolling updates

USE numbered lists for sequential steps:

## Installation

1. Clone the repository
2. Install dependencies
3. Configure environment variables
4. Run the application

Table Formatting

MUST align table columns:

| Name     | Type    | Required | Default |
| -------- | ------- | -------- | ------- |
| replicas | integer | Yes      | -       |
| image    | string  | Yes      | -       |
| port     | integer | No       | 8080    |

Links and References

Internal Links

MUST use relative paths for internal links:

For more details, see the [deployment guide](../how-to/how-to-deploy.md).

Related documentation:

- [Monitoring setup](./how-to-monitoring.md)
- [Architecture overview](../concepts/concept-architecture.md)

External Links

MUST use descriptive link text:

Refer to the [Azure AKS documentation](https://docs.microsoft.com/azure/aks/)
for platform-specific details.

❌ Bad: Click [here](https://example.com) for more info.
✅ Good: See the [troubleshooting guide](https://example.com/troubleshoot).

Admonitions

USE standard admonition patterns:

> **Note:** This is informational content that supplements the main text.

> **Warning:** This highlights potential issues or gotchas.

> **Important:** This is critical information that must not be missed.

> **Tip:** This provides helpful suggestions or shortcuts.

For extended content:

> **⚠️ Warning**
>
> Extended warning content that spans multiple lines.
> Include specific details about the risk and mitigation.

Screenshots and Diagrams

Image Guidelines

MUST include alt text for accessibility:

![Azure portal showing resource group creation](./images/azure-create-rg.png)

MUST store images in an images/ or assets/ subdirectory:

docs/
├── how-to-deploy.md
└── images/
    └── deploy-workflow.png

Mermaid Diagrams

PREFER Mermaid for diagrams (renders in megadoc):

```mermaid
graph TD
    A[User Request] --> B{Load Balancer}
    B --> C[Service A]
    B --> D[Service B]
    C --> E[(Database)]
    D --> E
```

Content Guidelines

Voice and Tone

USE active voice and direct language:

❌ The configuration file should be edited by the user.
✅ Edit the configuration file.

❌ It is recommended that you back up your data.
✅ Back up your data before proceeding.

Avoid Vague Language

NEVER use vague or ambiguous terms:

❌ Configure the appropriate settings.
✅ Set `maxRetries` to 3 and `timeout` to 30 seconds.

❌ Use best practices for security.
✅ Enable TLS 1.2, disable public access, use managed identities.

❌ Various options are available.
✅ Available options: Standard_D2s_v3, Standard_D4s_v3, Standard_D8s_v3.

Prerequisites Section

MUST include prerequisites for how-to guides and runbooks:

## Prerequisites

Before starting, ensure you have:

- [ ] Azure CLI installed (version 2.40+)
- [ ] kubectl configured with cluster access
- [ ] Membership in the `platform-operators` group
- [ ] Access to the production Key Vault

Review and Maintenance

Review Cycle

MUST review documents:

• Stable docs: Every 6 months
• Experimental docs: Every 3 months
• Runbooks: After every major incident

Deprecation Process

When deprecating documentation:

1. Update lifecycle_status to deprecated
2. Add deprecation notice at top:

> **⚠️ Deprecated**
>
> This document is deprecated as of 2024-12-19.
> See [new-document.md](./new-document.md) for updated guidance.

1. Keep for 90 days before removal
2. Set up redirect if URL is shared externally

Validation Checklist

Before submitting documentation:

• YAML front matter complete and valid
• Correct Diátaxis prefix used
• Single H1 heading matching title
• No skipped heading levels
• All code blocks have language annotations
• All images have alt text
• Internal links use relative paths
• No vague language ("various", "appropriate", "etc.")
• Prerequisites listed (for how-to/runbooks)
• Last reviewed date updated