documentation-writing

文档编写技能

目的

按照八项规则和 Diataxis 框架编写高质量、易于发现的文档。确保所有文档都位于正确位置、相互链接，并包含真实可运行的示例。

激活时机

提到以下内容时，我会自动加载：

• “编写文档”或“创建文档”
• “记录此功能／模块／API”
• “创建 README”或“编写教程”
• “解释其工作原理”
• 任何创建 Markdown 文档的请求

核心规则（必须遵守）

八项规则

1. 位置：所有文档都放在 docs/ 目录中
2. 链接：每篇文档都至少从另一篇文档链接
3. 简洁：使用通俗语言，删去不必要的词语
4. 真实示例：使用可运行的代码，而非“foo/bar”占位符
5. Diataxis：每个文件只包含一种文档类型（教程／操作指南／参考／说明）
6. 易于浏览：使用描述性标题，长文档应包含目录
7. 本地链接：使用相对路径，并在链接附近提供上下文
8. 保持更新：删除过时文档，并包含更新元数据

文档中不应包含的内容

切勿放入 docs/：

• 状态报告或进度更新
• 测试结果或基准测试
• 会议记录或决策
• 带日期的计划
• 特定时间点的快照

时间性信息的归属位置：

• 测试结果 → CI 日志、GitHub Actions
• 状态更新 → GitHub Issues
• 进度 → Pull Request 描述
• 决策 → Commit 消息

快速开始

创建新文档

# [Feature Name]

Brief one-sentence description of what this is.

## Quick Start

Minimal steps to get started (3-5 steps max).

## Contents

- [Configuration](#configuration)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)

## Configuration

Step-by-step setup with real examples.

## Usage

Common use cases with runnable code.

## Troubleshooting

Common problems and solutions.

文档类型（Diataxis）

类型	目的	位置	用户疑问
教程	学习	docs/tutorials/	“教我如何操作”
操作指南	执行操作	docs/howto/	“帮我完成 X”
参考	获取信息	docs/reference/	“有哪些选项？”
说明	理解	docs/concepts/	“为什么要这样设计？”

工作流

步骤 1：确定文档类型

思考：读者想要完成什么？

• 学习新内容 → 教程
• 解决特定问题 → 操作指南
• 查阅详细信息 → 参考
• 理解概念 → 说明

步骤 2：选择位置

docs/
├── tutorials/     # Learning-oriented
├── howto/         # Task-oriented
├── reference/     # Information-oriented
├── concepts/      # Understanding-oriented
└── index.md       # Links to all docs

步骤 3：编写示例

每个概念都需要一个可运行的示例：

# Example: Analyze file complexity
from amplihack import analyze

result = analyze("src/main.py")
print(f"Complexity: {result.score}")
# Output: Complexity: 12.5

步骤 4：从索引添加链接

在 docs/index.md 中添加条目：

- [New Feature Guide](./howto/new-feature.md) - How to configure X

步骤 5：验证

完成前检查：

• 文件位于 docs/ 目录中
• 已从索引或上级文档链接
• 不包含时间性信息
• 已测试所有示例
• 符合一种 Diataxis 文档类型

导航指南

何时阅读辅助文件

reference.md - 以下情况请阅读：

• 需要完整的 frontmatter 规范
• 需要详细了解 Diataxis 类型定义
• 需要了解 Markdown 风格规范
• 需要查看文档审查清单

examples.md - 以下情况请阅读：

• 需要各类型文档的完整模板
• 需要查看真实的文档示例
• 需要查看改进前后的示例
• 需要了解复杂的文档模式

应避免的反模式

反模式	不足之处	更好的做法
“点击此处”链接	缺少上下文	“参见 身份验证配置”
foo/bar 示例	不够真实	使用项目中的真实代码
大段文字	难以浏览	使用标题和项目符号
孤立文档	无人发现	从索引添加链接
在文档中写状态信息	容易过时	使用 Issues/PRs

追溯式文档编写例外

在实现之前编写文档时（文档驱动开发）：

# [PLANNED - Implementation Pending]

This document describes the intended behavior of Feature X.

## Planned Interface

```python
# [PLANNED] - This API will be implemented
def future_function(input: str) -> Result:
    """Process input and return result."""
    pass
```

实现完成后，移除 [PLANNED] 标记，并替换为真实示例。

---

**Full reference**: See [reference.md](./reference.md) for complete specification.
**Templates**: See [examples.md](./examples.md) for copy-paste templates.