Documentation Standards

Overview

Standards for writing markdown documentation optimized for both LLM consumption and conversion to professional PDFs using Pandoc. Ensures consistency across all documentation in ~/.claude/ workspace.

When to Use This Skill

Use when:

• •Writing markdown documentation (README, skills, guides, specifications)
• •Creating new skills that include markdown content
• •Authoring content that may be converted to PDF
• •Reviewing documentation for standards compliance

Core Principles

1. LLM-Optimized Documentation Architecture

Machine-Readable Priority: OpenAPI 3.1.0 specs, JSON Schema, YAML specifications take precedence over human documentation.

Why: Structured formats provide unambiguous contracts that both humans and LLMs can consume reliably. Human docs supplement, don't replace, machine-readable specs.

Application:

• •Workflow specifications → OpenAPI 3.1.1 YAML in ~/.claude/specifications/
• •Data schemas → JSON Schema with examples
• •Configuration → YAML with validation schemas
• •Human docs → Markdown referencing canonical machine-readable specs

2. Hub-and-Spoke Progressive Disclosure

Pattern: Central hubs (like CLAUDE.md, INDEX.md) link to detailed spokes (skills, docs directories).

Structure:

CLAUDE.md (Hub - Essentials Only)
    ↓ links to
Skills (Spokes - Progressive Disclosure)
    ├── SKILL.md (Overview + Quick Start)
    └── references/ (Detailed Documentation)

Rules:

• •Hubs contain essentials only (what + where to find more)
• •Spokes contain progressive detail (load as needed)
• •Single source of truth per topic (no duplication)

3. Markdown Section Numbering

Critical Rule: Never manually number markdown headings.

❌ Wrong:

## 1. Introduction
### 1.1 Background
### 1.2 Objectives
## 2. Implementation

✅ Correct:

## Introduction
### Background
### Objectives
## Implementation

Rationale:

• •Pandoc's --number-sections flag auto-numbers all sections when generating PDFs
• •Manual numbering creates duplication: "1. 1. Introduction" in rendered output
• •Auto-numbering is consistent, updates automatically when sections reorganize
• •Applies to ALL markdown: documentation, skills, project files, README files

Rule: If markdown might ever convert to PDF, never manually number headings. Use semantic heading levels (##, ###) and let tools handle numbering.

PDF Generation: See pandoc-pdf-generation skill for implementation details.

Standards Checklist

Use this checklist when creating or reviewing documentation:

Structure

• • Follows hub-and-spoke pattern (essentials in main doc, details in references)
• • Links to deeper documentation for progressive disclosure
• • Single source of truth (no duplicate content across docs)

Markdown Formatting

• • No manual section numbering in headings
• • Semantic heading levels (##, ###, ####) used correctly
• • Code blocks have language identifiers for syntax highlighting
• • Links use markdown format [text](url), not bare URLs

Machine-Readable Content

• • Workflows documented as OpenAPI 3.1.1 specs (when applicable)
• • Data structures use JSON Schema (when applicable)
• • Configuration uses YAML with validation (when applicable)
• • Human docs reference canonical machine-readable specs

File Organization

• • Documentation lives in appropriate location:
  • •Global standards → ~/.claude/docs/standards/
  • •Skill documentation → ~/.claude/skills/{skill-name}/references/
  • •Project documentation → {project}/.claude/ or {project}/docs/
• • Index files provide navigation (INDEX.md, README.md)

Related Resources

• •PDF Generation: pandoc-pdf-generation - Markdown to PDF conversion
• •Skill Architecture: skill-architecture - Creating effective skills
• •Documentation Hub: ~/.claude/docs/INDEX.md - Full documentation index

Examples

Good Hub-and-Spoke Structure

Hub (CLAUDE.md):

## PDF Generation from Markdown

**Quick Start**: Use [`pandoc-pdf-generation`](skills/pandoc-pdf-generation/SKILL.md) skill

**Critical Rules**:
1. Never write ad-hoc pandoc commands
2. Always verify PDFs before presenting
3. See skill for detailed principles

Spoke (pandoc-pdf-generation/SKILL.md):

• •Quick start with examples
• •Link to references/ for detailed documentation
• •Progressive disclosure as needed

Good Machine-Readable Documentation

Workflow Specification (specifications/hook-prompt-capture.yaml):

openapi: 3.1.1
info:
  title: Hook Prompt Capture Workflow
  version: 1.0.0
paths:
  /capture-prompt:
    post:
      summary: Capture user prompt from hook
      # ... detailed spec

Human Documentation (README.md):

## Workflow

See [hook-prompt-capture.yaml](specifications/hook-prompt-capture.yaml)
for complete workflow specification.

Quick overview: ...

Summary

Documentation standards ensure:

• •Consistency across all workspace documentation
• •LLM optimization through machine-readable formats
• •Maintainability via hub-and-spoke + single source of truth
• •PDF compatibility through proper markdown formatting

Follow these standards for all documentation in ~/.claude/ workspace.