Back to Details

documentation-standards

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
本标准针对同时适配LLM读取和通过Pandoc转换为专业PDF的Markdown文档编写制定，确保所有文档的一致性。

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
在以下场景中使用：
  • 编写Markdown文档（README、技能文档、指南、规范）
  • 创建包含Markdown内容的新技能文档
  • 撰写可能需要转换为PDF的内容
  • 审查文档是否符合标准

Core Principles

核心原则

1. LLM-Optimized Documentation Architecture

1. 适配LLM的文档架构

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 specifications/
  • Data schemas → JSON Schema with examples
  • Configuration → YAML with validation schemas
  • Human docs → Markdown referencing canonical machine-readable specs
机器可读优先：OpenAPI 3.1.0规范、JSON Schema、YAML规格说明的优先级高于人工编写的文档。
原因：结构化格式提供了人类和LLM都能可靠读取的明确约定。人工文档仅作为补充，不能替代机器可读的规范。
应用场景：
  • 工作流规范 → 存放于specifications/目录下的OpenAPI 3.1.1 YAML文件
  • 数据架构 → 带示例的JSON Schema
  • 配置文件 → 带验证规则的YAML
  • 人工文档 → 引用权威机器可读规范的Markdown文档

2. Hub-and-Spoke Progressive Disclosure

2. 中心辐射式渐进披露模式

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)
模式：中心文档（如CLAUDE.md、INDEX.md）链接到详细的分支文档（技能文档、子目录下的文档）。
结构：
CLAUDE.md (中心文档 - 仅包含核心内容)
    ↓ 链接到
Skills (分支文档 - 渐进式披露细节)
    ├── SKILL.md (概述 + 快速入门)
    └── references/ (详细文档)
规则：
  • 中心文档仅包含核心内容（是什么 + 在哪里找到更多信息）
  • 分支文档包含渐进式的详细内容（按需加载）
  • 每个主题仅有单一事实来源（避免重复）

3. Markdown Section Numbering

3. Markdown章节编号

Critical Rule: Never manually number markdown headings.
❌ Wrong:
markdown
undefined
关键规则：切勿手动为Markdown标题编号。
❌ 错误示例：
markdown
undefined

1. Introduction

1. 引言

1.1 Background

1.1 背景

1.2 Objectives

1.2 目标

2. Implementation

2. 实现方案


✅ **Correct**:

```markdown

✅ **正确示例**：

```markdown

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.

**理由**：

- Pandoc的`--number-sections`参数在生成PDF时会自动为所有章节编号
- 手动编号会导致重复：在渲染后的输出中出现“1. 1. 引言”这类问题
- 自动编号保持一致性，当章节重组时会自动更新
- 适用于所有Markdown文档：说明文档、技能文档、项目文件、README文件

**规则**：如果Markdown文档可能需要转换为PDF，绝对不要手动为标题编号。使用语义化标题层级（##、###），让工具处理编号。

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

Markdown格式

  • 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
  • 标题中无手动章节编号
  • 正确使用语义化标题层级（##、###、####）
  • 代码块包含语言标识符以实现语法高亮
  • 链接使用Markdown格式
    [文本](链接地址)
    ，而非裸链接

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
  • 工作流文档采用OpenAPI 3.1.1规范（适用时）
  • 数据结构使用JSON Schema（适用时）
  • 配置文件使用带验证规则的YAML（适用时）
  • 人工文档引用权威的机器可读规范

File Organization

文件组织

  • Documentation lives in appropriate location:
    • Global standards → docs/standards/
    • Skill documentation → skills/{skill-name}/references/
    • Project documentation → {project}/.claude/ or {project}/docs/
  • Index files provide navigation (INDEX.md, README.md)
  • 文档存放于合适的位置：
    • 全局标准 → docs/standards/
    • 技能文档 → skills/{技能名称}/references/
    • 项目文档 → {项目目录}/.claude/ 或 {项目目录}/docs/
  • 存在索引文件提供导航（INDEX.md、README.md）

Related Resources

相关资源

  • ASCII Diagram Validation: ascii-diagram-validator - Validate ASCII diagrams in markdown
  • Skill Architecture: See skill-architecture plugin for creating effective skills
  • ASCII图验证：ascii-diagram-validator - 验证Markdown中的ASCII图
  • 技能架构：查看skill-architecture插件以创建有效的技能文档

Examples

示例

Good Hub-and-Spoke Structure

良好的中心辐射式结构

Hub (CLAUDE.md):
markdown
undefined
中心文档（CLAUDE.md）：
markdown
undefined

PDF Generation from Markdown

从Markdown生成PDF

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

**Spoke (skill/SKILL.md)**:

- Quick start with examples
- Link to references/ for detailed documentation
- Progressive disclosure as needed
快速入门：使用pandoc-pdf-generation技能文档
关键规则：
  1. 切勿编写临时的pandoc命令
  2. 展示前务必验证PDF
  3. 详细原则请查看技能文档

**分支文档（skill/SKILL.md）**：

- 带示例的快速入门
- 链接到references/目录下的详细文档
- 按需提供渐进式披露的内容

Good Machine-Readable Documentation

良好的机器可读文档

Workflow Specification (specifications/hook-prompt-capture.yaml):
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):
markdown
undefined
工作流规范（specifications/hook-prompt-capture.yaml）：
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
      # ... 详细规范
人工文档（README.md）：
markdown
undefined

Workflow

工作流

See hook-prompt-capture.yaml for complete workflow specification.
Quick overview: ...
undefined
完整的工作流规范请查看hook-prompt-capture.yaml。
快速概览：...
undefined

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.
文档标准确保：
  • 一致性：所有工作区文档保持一致
  • LLM适配性：通过机器可读格式优化
  • 可维护性：借助中心辐射式模式 + 单一事实来源
  • PDF兼容性：通过正确的Markdown格式实现
所有文档请遵循本标准。

Troubleshooting

故障排除

IssueCauseSolution
Double section numbers in PDFManual numbering in markdownRemove manual numbers, use --number-sections only
Broken links in PDFRelative paths incorrectUse repo-root paths for cross-document links
Code block no syntax colorMissing language identifierAdd language after opening triple backticks
Tables render poorlyColumn widths too wideUse shorter headers or pipe-table format
Hub doc too longToo much detail in hubMove details to spoke documents, link from hub
Duplicate contentSame info in multiple docsIdentify SSoT, remove duplicates, add links
YAML spec not renderingWrong file extensionUse .yaml extension for OpenAPI specs
Index navigation missingNo INDEX.md or README.mdCreate navigation index in each directory
问题原因解决方案
PDF中出现重复章节编号Markdown中存在手动编号删除手动编号，仅使用--number-sections参数
PDF中的链接失效相对路径不正确跨文档链接使用仓库根目录路径
代码块无语法高亮缺少语言标识符在开头的三个反引号后添加语言标识
表格渲染效果差列宽过宽使用更短的表头或管道表格格式
中心文档过长中心文档包含过多细节将细节移至分支文档，从中心文档添加链接
内容重复同一信息出现在多个文档中确定单一事实来源，删除重复内容，添加链接
YAML规范无法渲染文件扩展名错误OpenAPI规范使用.yaml扩展名
缺少索引导航无INDEX.md或README.md在每个目录下创建导航索引
undefined