documentation-guide

Documentation Guide

Language: English | 繁體中文

Version: 2.1.0 Last Updated: 2026-03-17 Applicability: Claude Code Skills

Purpose

This skill provides comprehensive guidance on project documentation, including:

• Documentation structure and file organization
• Content requirements by project type
• Writing standards for technical documents
• Templates for common documentation types

Quick Reference (YAML Compressed)

# === PROJECT TYPE → DOCUMENT REQUIREMENTS ===
document_matrix:
  #           README  ARCH   API    DB     DEPLOY MIGRATE ADR    CHANGE CONTRIB
  new:        [REQ,   REQ,   if_app, if_app, REQ,   NO,     REC,   REQ,   REC]
  refactor:   [REQ,   REQ,   REQ,    REQ,    REQ,   REQ,    REQ,   REQ,   REC]
  migration:  [REQ,   REQ,   REQ,    REQ,    REQ,   REQ,    REQ,   REQ,   REC]
  maintenance:[REQ,   REC,   REC,    REC,    REC,   NO,     if_app, REQ,   if_app]
  # REQ=Required, REC=Recommended, if_app=If applicable, NO=Not needed

# === DOCUMENTATION PYRAMID ===
pyramid:
  level_1: "README.md → Entry point, quick overview"
  level_2: "ARCHITECTURE.md → System overview"
  level_3: "API.md, DATABASE.md, DEPLOYMENT.md → Technical details"
  level_4: "ADR/, MIGRATION.md, CHANGELOG.md → Change history"

# === ESSENTIAL FILES ===
root_files:
  README.md: {required: true, purpose: "Project overview, quick start"}
  CONTRIBUTING.md: {required: "recommended", purpose: "Contribution guidelines"}
  CHANGELOG.md: {required: "recommended", purpose: "Version history"}
  LICENSE: {required: "for OSS", purpose: "License information"}

docs_structure:
  INDEX.md: "Documentation index"
  ARCHITECTURE.md: "System architecture"
  API.md: "API documentation"
  DATABASE.md: "Database schema"
  DEPLOYMENT.md: "Deployment guide"
  MIGRATION.md: "Migration plan (if applicable)"
  ADR/: "Architecture Decision Records"

# === FILE NAMING ===
naming:
  root: "UPPERCASE.md (README.md, CONTRIBUTING.md, CHANGELOG.md)"
  docs: "lowercase-kebab-case.md (getting-started.md, api-reference.md)"

# === QUALITY STANDARDS ===
quality:
  format:
    language: "English (or project-specified)"
    encoding: "UTF-8"
    line_length: "≤120 characters recommended"
    diagrams: "Mermaid preferred, then ASCII Art"
    links: "Relative paths for internal links"
  maintenance:
    sync: "Update docs when code changes"
    version: "Mark version and date at top"
    review: "Include docs in code review"
    periodic: "Review quarterly for staleness"

# === DIÁTAXIS CLASSIFICATION ===
diataxis:
  tutorial: "Learning-oriented (getting-started.md)"
  how_to: "Task-oriented (deployment.md, migration.md)"
  reference: "Information-oriented (api-reference.md, CHANGELOG.md)"
  explanation: "Understanding-oriented (architecture.md, ADR/)"
  header: "Add **Document Type**: Tutorial | How-to | Reference | Explanation"

# === LLM DISCOVERY ===
llm_discovery:
  llms_txt: "Structured index at project root for LLM retrieval"
  llms_full_txt: "Optional full concatenated docs"
  when: "Public projects, public APIs, projects using AI tools"

# === QUALITY METRICS ===
quality_metrics:
  leading: ["Coverage ≥90%", "Freshness ≤90d", "Link Health 100%", "Example Validity 100%"]
  lagging: ["Support ticket reduction", "Onboarding time", "Doc-related PR comments"]
  tools: [markdown-link-check, lychee, remark-lint, vale, textstat]

# === ADR ENHANCED ===
adr_enhanced:
  new_fields: [Date, Deciders, Drivers, "supersedes/superseded-by"]
  lifecycle: "proposed → accepted → [deprecated | superseded]"
  decision_matrix: "impact × reversibility → ADR required?"

# === TRANSLATION-FRIENDLY ===
translation_friendly:
  rules: ["Complete sentences", "No idioms", "Consistent terminology", "Simple SVO", "Explicit references"]
  glossary: "Maintain glossary.md for term consistency"
  status_tracking: "YAML frontmatter with translation_status, source_version"