meta:write-docs

Table of Contents

• When to Use
• Document Structure
• Formatting Rules
• Diagrams
• Tables
• Code Blocks
• Cross-References
• Checklist
• Template

When to Use

• Creating new documentation under docs/
• Writing design documents, guides, or reference material
• Updating existing docs with new sections

Document Structure

Every document follows this skeleton:

# Title

Brief one-paragraph description of what this document covers and who it is for.

## Table of Contents

- [Section One](#section-one)
- [Section Two](#section-two)
  - [Subsection](#subsection)

---

## Section One

Content here.

---

## Section Two

### Subsection

Content here.

Rules:

1. Single # title at the top
2. One-paragraph overview immediately after the title
3. TOC with anchor links for documents over 50 lines
4. --- horizontal rules between major sections
5. Keep explanations concise - prefer bullets and tables over prose
6. Use ### subsections to break up long sections

Formatting Rules

Text

• Bold for key terms, component names, and emphasis
• inline code for commands, file paths, variable names, API endpoints
• Italic for introducing new terminology (first use only)
• Blockquotes for callouts:

> **Note:** Additional context that supplements the main text.

> **Warning:** Something that can cause problems if ignored.

> **Prerequisite:** Something required before proceeding.

Lists

• Bullet lists (-) for unordered items
• Numbered lists (1.) for sequential steps or ranked items
• Keep list items concise (1-2 lines)
• Nest at most 2 levels deep

Expandable Sections

Use <details> for optional or advanced content:

<details>
<summary>Advanced: Custom collector configuration</summary>

Content that most readers can skip.

</details>

Diagrams

Mermaid (for flows and relationships)

Use Mermaid for process flows, state machines, and component relationships. Wrap in ```mermaid code fences:

` ` `mermaid
flowchart LR
    A[Source] --> B[Processor]
    B --> C[Exporter]
` ` `

Mermaid patterns:

Type	Use Case	Directive
flowchart LR	Left-to-right process flows	Data pipelines, request flows
flowchart TB	Top-to-bottom hierarchies	Component trees, deployment order
sequenceDiagram	Request/response interactions	API calls, auth flows
stateDiagram-v2	Lifecycle states	Pod states, build stages
graph TB with subgraph	Grouped components	Architecture with namespaces

Style tips:

• Use subgraph to group related components (e.g., by namespace or cluster)
• Add labels on edges: A -->|"OTLP gRPC"| B
• Keep node labels short (3-4 words max)
• Use :::className for visual distinction when needed

ASCII Art (for architecture layouts)

Use ASCII art for spatial layouts showing where components live physically (clusters, namespaces, nodes). Wrap in ```text or ```shell:

+----------------------------+
|    Management Cluster      |
|  +--------+  +---------+  |
|  | Prom   |  | Alerts  |  |
|  +---^----+  +----^----+  |
+------|-----------|---------+
       |           |
+------|-----------|---------+
|    Hosted Cluster          |
|  +--------+  +---------+  |
|  | OTEL   |  | Agents  |  |
|  +--------+  +---------+  |
+----------------------------+

ASCII art rules:

• Use +, -, | for borders (not Unicode box-drawing characters in code blocks)
• Use ^, v, <, > for directional arrows
• Align columns for readability
• Label every box
• Keep width under 80 characters

When to use which

Scenario	Use
Data flows, pipelines	Mermaid flowchart
API interactions	Mermaid sequenceDiagram
Cluster/namespace layouts	ASCII art
Component lifecycle	Mermaid stateDiagram
Decision trees	Mermaid flowchart with conditions

Tables

Use tables for structured reference data. Keep column count to 3-5:

| Component | Purpose | Namespace |
|-----------|---------|-----------|
| OTEL Collector | Telemetry pipeline | `rossoctl-system` |
| TempoStack | Trace storage | `tempo-system` |

Table rules:

• Header row always present
• Left-align text, right-align numbers
• Use inline code for technical values
• Keep cell content to 1 line when possible

Code Blocks

Commands

Always specify language. Use bash for shell commands:

```bash
kubectl get pods -n rossoctl-system
```

YAML/JSON manifests

Include just the relevant fields, not entire manifests. Add a comment at the top identifying the resource:

```yaml
# charts/rossoctl/templates/observability/collector.yaml
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: rossoctl-collector
spec:
  mode: daemonset
```

Expected output

Show expected output after commands when it aids understanding:

```bash
kubectl get tempostacks -n tempo-system
```

```text
NAME            AGE   STATUS
rossoctl-tempo   5m    Ready
```

Cross-References

• Link to other docs with relative paths: [Components](../components.md)
• Link to source files: [check-capacity.sh](../../.github/scripts/hypershift/ci/slots/check-capacity.sh)
• Link to external references at the bottom in a ## References section
• Use descriptive link text, not "click here"

Checklist

Before committing documentation:

• Title and one-paragraph overview present
• TOC with working anchor links (if >50 lines)
• Sections separated by ---
• Code blocks have language tags
• Diagrams render correctly (Mermaid syntax valid, ASCII aligned)
• Tables have header rows
• Cross-references use relative paths
• No broken links
• Concise - no unnecessary prose

Template

# Document Title

Brief description of what this document covers and its audience.

## Table of Contents

- [Overview](#overview)
- [Architecture](#architecture)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
- [References](#references)

---

## Overview

Context and goals in 2-3 sentences.

---

## Architecture

` ` `mermaid
flowchart LR
    A[Component A] -->|protocol| B[Component B]
` ` `

---

## Configuration

### Component Name

` ` `yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: example
` ` `

| Parameter | Default | Description |
|-----------|---------|-------------|
| `key` | `value` | What it does |

---

## Troubleshooting

### Problem: Description

**Symptom**: What you observe
**Cause**: Why it happens
**Fix**: How to resolve

---

## References

- [External Doc](https://example.com)
- [Related Internal Doc](../related.md)

Related Skills

• skills:write - Template for creating skills (different from docs)