Back to Details

documentation-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Writing Skill

文档编写Skill

Purpose

用途

Creates high-quality, discoverable documentation following the Eight Rules and Diataxis framework. Ensures all docs are properly located, linked, and contain real runnable examples.
遵循八项规则与Diataxis框架，创建高质量、易于查找的文档。确保所有文档存放位置正确、链接得当，并包含真实可运行的示例。

When I Activate

触发条件

I load automatically when you mention:
  • "write documentation" or "create docs"
  • "document this feature/module/API"
  • "create a README" or "write a tutorial"
  • "explain how this works"
  • Any request to create markdown documentation
当你提及以下内容时，我会自动加载：
  • "编写文档"或"创建文档"
  • "为该功能/模块/API编写文档"
  • "创建README"或"编写教程"
  • "解释其工作原理"
  • 任何创建Markdown文档的请求

Core Rules (MANDATORY)

核心规则（强制性）

The Eight Rules

八项规则

  1. Location: All docs in 
    docs/
    directory
  2. Linking: Every doc linked from at least one other doc
  3. Simplicity: Plain language, remove unnecessary words
  4. Real Examples: Runnable code, not "foo/bar" placeholders
  5. Diataxis: One doc type per file (tutorial/howto/reference/explanation)
  6. Scanability: Descriptive headings, table of contents for long docs
  7. Local Links: Relative paths, context with links
  8. Currency: Delete outdated docs, include update metadata
  1. 位置：所有文档存放于
    docs/
    目录
  2. 链接：每个文档至少与其他一个文档建立链接
  3. 简洁：使用平实语言，删除冗余词汇
  4. 真实示例：使用可运行代码，而非"foo/bar"占位符
  5. Diataxis规范：每个文件对应一种文档类型（教程/操作指南/参考文档/说明文档）
  6. 易读性：使用描述性标题，长文档添加目录
  7. 本地链接：使用相对路径，通过链接提供上下文
  8. 时效性：删除过时文档，包含更新元数据

What Stays OUT of Docs

文档中禁止包含的内容

Never put in 
docs/
:
  • Status reports or progress updates
  • Test results or benchmarks
  • Meeting notes or decisions
  • Plans with dates
  • Point-in-time snapshots
Where temporal info belongs:
  • Test results → CI logs, GitHub Actions
  • Status updates → GitHub Issues
  • Progress → Pull Request descriptions
  • Decisions → Commit messages
切勿放入
docs/
目录的内容：
  • 状态报告或进度更新
  • 测试结果或基准数据
  • 会议记录或决策内容
  • 带日期的计划
  • 特定时间点的快照
时效性信息的正确存放位置：
  • 测试结果 → CI日志、GitHub Actions
  • 状态更新 → GitHub Issues
  • 进度情况 → Pull Request描述
  • 决策内容 → 提交信息

Quick Start

快速入门

Creating a New Document

创建新文档

markdown
undefined
markdown
undefined

[Feature Name]

[功能名称]

Brief one-sentence description of what this is.
简要的一句话描述该功能是什么。

Quick Start

快速入门

Minimal steps to get started (3-5 steps max).
入门的最少步骤（最多3-5步）。

Contents

目录

Configuration

配置

Step-by-step setup with real examples.
带真实示例的分步设置说明。

Usage

使用方法

Common use cases with runnable code.
带可运行代码的常见使用场景。

Troubleshooting

故障排除

Common problems and solutions.
undefined
常见问题及解决方案。
undefined

Document Types (Diataxis)

文档类型（Diataxis规范）

TypePurposeLocationUser Question
TutorialLearning
docs/tutorials/
"Teach me how"
How-ToDoing
docs/howto/
"Help me do X"
ReferenceInformation
docs/reference/
"What are the options?"
ExplanationUnderstanding
docs/concepts/
"Why is it this way?"
类型用途存放位置用户问题
Tutorial学习指导
docs/tutorials/
"教我如何操作"
How-To操作指南
docs/howto/
"帮我完成X操作"
Reference信息查询
docs/reference/
"有哪些选项？"
Explanation概念说明
docs/concepts/
"为什么要这样设计？"

Workflow

工作流程

Step 1: Determine Document Type

步骤1：确定文档类型

Ask: What is the reader trying to accomplish?
  • Learning something new → Tutorial
  • Solving a specific problem → How-To
  • Looking up details → Reference
  • Understanding concepts → Explanation
思考：读者想要达成什么目标？
  • 学习新知识 → 教程
  • 解决特定问题 → 操作指南
  • 查阅详细信息 → 参考文档
  • 理解概念 → 概念说明

Step 2: Choose Location

步骤2：选择存放位置

docs/
├── tutorials/     # Learning-oriented
├── howto/         # Task-oriented
├── reference/     # Information-oriented
├── concepts/      # Understanding-oriented
└── index.md       # Links to all docs
docs/
├── tutorials/     # 学习导向
├── howto/         # 任务导向
├── reference/     # 信息导向
├── concepts/      # 理解导向
└── index.md       # 所有文档的链接入口

Step 3: Write with Examples

步骤3：编写并添加示例

Every concept needs a runnable example:
python
undefined
每个概念都需要可运行的示例：
python
undefined

Example: Analyze file complexity

示例：分析文件复杂度

from amplihack import analyze
result = analyze("src/main.py") print(f"Complexity: {result.score}")
from amplihack import analyze
result = analyze("src/main.py") print(f"复杂度: {result.score}")

Output: Complexity: 12.5

输出: 复杂度: 12.5

undefined
undefined

Step 4: Link from Index

步骤4：从索引页添加链接

Add entry to 
docs/index.md
:
markdown
- [New Feature Guide](./howto/new-feature.md) - How to configure X
在
docs/index.md
中添加条目：
markdown
- [新功能指南](./howto/new-feature.md) - 如何配置X

Step 5: Validate

步骤5：验证

Checklist before completion:
  • File in 
    docs/
    directory
  • Linked from index or parent doc
  • No temporal information
  • All examples tested
  • Follows one Diataxis type
完成前的检查清单：
  • 文件存放于
    docs/
    目录
  • 已从索引页或父文档添加链接
  • 无时效性信息
  • 所有示例均已测试
  • 符合Diataxis的单一文档类型规范

Navigation Guide

导航指南

When to Read Supporting Files

何时阅读支持文件

reference.md - Read when you need:
  • Complete frontmatter specification
  • Detailed Diataxis type definitions
  • Markdown style conventions
  • Documentation review checklist
examples.md - Read when you need:
  • Full document templates for each type
  • Real-world documentation examples
  • Before/after improvement examples
  • Complex documentation patterns
reference.md - 当你需要以下信息时阅读：
  • 完整的前置规范
  • 详细的Diataxis类型定义
  • Markdown风格约定
  • 文档审核检查清单
examples.md - 当你需要以下信息时阅读：
  • 每种文档类型的完整模板
  • 真实场景的文档示例
  • 改进前后的示例对比
  • 复杂文档的编写模式

Anti-Patterns to Avoid

需避免的反模式

Anti-PatternWhy It's BadBetter Approach
"Click here" linksNo context"See auth config"
foo/bar examplesNot realisticUse real project code
Wall of textHard to scanUse headings and bullets
Orphan docsNever foundLink from index
Status in docsGets staleUse Issues/PRs
反模式问题所在更好的做法
"点击这里"链接无上下文信息"查看认证配置"
foo/bar占位示例不贴合实际使用真实项目代码
大段无格式文本难以快速浏览使用标题和列表
孤立文档永远无法被找到从索引页添加链接
文档中包含状态信息容易过时使用Issues/PRs

Retcon Documentation Exception

回溯文档例外情况

When writing documentation BEFORE implementation (document-driven development):
markdown
undefined
当在实现前编写文档时（文档驱动开发）：
markdown
undefined

[PLANNED - Implementation Pending]

[计划中 - 待实现]

This document describes the intended behavior of Feature X.
本文档描述了功能X的预期行为。

Planned Interface

计划中的接口

python
undefined
python
undefined

[PLANNED] - This API will be implemented

[计划中] - 该API将被实现

def future_function(input: str) -> Result: """Process input and return result.""" pass
undefined
Once implemented, remove the 
[PLANNED]
markers and update with real examples.

---

**Full reference**: See [reference.md](./reference.md) for complete specification.
**Templates**: See [examples.md](./examples.md) for copy-paste templates.
def future_function(input: str) -> Result: """处理输入并返回结果。""" pass
undefined
实现完成后，移除
[计划中]
标记并更新为真实示例。
完整参考：请查看reference.md获取完整规范。 模板：请查看examples.md获取可直接复制使用的模板。