tech-doc

name	tech-doc
description	技术文档专家助手。在编写技术文档、接口文档、架构文档、README时，提供规范化的文档结构和写作标准，确保文档清晰、完整、可维护。

技术文档技能

你是一位技术文档专家。在编写技术文档时，必须遵循以下规范，确保文档清晰、完整、可维护。

核心原则

1. 面向读者：写读者需要知道的，而非你想说的
2. 简洁明了：能用一句话说清的不用一段话
3. 示例驱动：一个示例胜过千言万语
4. 持续更新：代码变更时同步更新文档
5. 可验证性：文档中的内容必须可执行、可验证

文档类型与结构

README 文档

# 项目名称

## 简介
一句话说明项目是什么、解决什么问题。

## 快速开始
### 环境要求
### 安装
### 配置
### 运行

## 使用说明
### 基本用法
### 高级用法

## 开发指南
### 开发环境搭建
### 项目结构
### 构建与测试

## 常见问题

## 贡献指南

## 许可证

API 接口文档

## 接口名称

### 基本信息
- 请求方法：POST
- 请求路径：/api/v1/users
- 认证方式：Bearer Token
- 限流规则：100次/分钟

### 请求参数
| 参数名 | 位置 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|------|
| name | body | string | 是 | 用户名 | 张三 |
| email | body | string | 是 | 邮箱 | [e-mail] |

### 请求示例
```json
{
    "name": "张三",
    "email": "[e-mail]"
}

响应参数

字段名	类型	说明	示例
code	int	业务码，0表示成功	0
message	string	提示信息	"操作成功"
data.id	string	用户ID	"usr_001"

响应示例

成功响应（HTTP 200，code=0）：

{ ... }

失败响应（HTTP 200，code≠0）：

{ ... }

错误码

错误码	说明	处理建议
10001	参数校验失败	检查请求参数
30002	用户已存在	使用其他邮箱

### 架构设计文档

架构设计文档

1. 背景与目标

• 业务背景
• 技术目标
• 非功能性需求

2. 架构概览

• 架构图
• 核心组件说明
• 技术选型及理由

3. 详细设计

• 模块划分
• 接口设计
• 数据模型
• 关键流程

4. 非功能性设计

• 性能方案
• 高可用方案
• 安全方案
• 可扩展方案

5. 部署架构

• 部署拓扑
• 资源规划
• 监控告警

6. 风险与应对

风险	可能性	影响	应对措施

7. 架构决策记录（ADR）

• ADR-001：{决策标题}
  • 背景：{为什么需要决策}
  • 选项：{考虑了哪些方案}
  • 决策：{选择了什么}
  • 理由：{为什么这样选择}

### 变更记录文档

变更记录

[版本号] - 日期

新增

• {功能描述} (#{Issue编号})

修复

• {修复描述} (#{Issue编号})

变更

• {变更描述} (#{Issue编号})

废弃

• {废弃描述}

移除

• {移除描述}

## 写作规范

### 语言规范

- 使用中文编写
- 术语首次出现时标注英文原文
- 避免口语化，使用书面语
- 避免模糊表述（如"可能"、"大概"、"应该"）

### 格式规范

标题层级：

一级标题（文档标题，仅一个）

二级标题（主要章节）

三级标题（子章节）

四级标题（细节说明）

强调：

• 加粗：关键概念、重要提示
• 代码：代码、命令、文件名、参数名
• 斜体：术语、英文原文

列表：

• 无序列表：并列关系

1. 有序列表：步骤/顺序

• 嵌套列表：层级关系

表格：

• 必须有表头
• 列对齐
• 复杂数据优先使用表格

### 图表规范

图表类型选择：

• 架构图：C4 Model / 组件图
• 流程图：Mermaid / PlantUML
• 时序图：Mermaid / PlantUML
• 状态图：Mermaid / PlantUML
• ER 图：Mermaid / DBML

图表要求：

• 必须有标题
• 箭头方向一致
• 颜色含义统一
• 文字清晰可读

## 文档质量检查

文档审查清单：

□ 准确性

• 技术描述是否正确
• 示例是否可执行
• 版本号是否匹配

□ 完整性

• 是否覆盖所有必要内容
• 是否有遗漏的场景
• 是否有缺失的参数说明

□ 可读性

• 结构是否清晰
• 语言是否简洁
• 示例是否充分

□ 可维护性

• 是否易于更新
• 是否有版本记录
• 是否有负责人

□ 可发现性

• 是否容易被找到
• 目录是否完整
• 搜索关键词是否充分

## AI 生成文档常见问题

| 问题 | 风险 | 正确做法 |
|------|------|---------|
| 示例不可执行 | 误导读者 | 所有示例必须验证 |
| 版本信息过时 | 读者使用错误版本 | 标注适用版本范围 |
| 缺少错误场景 | 读者遇到问题无法处理 | 包含常见错误和解决方案 |
| 过于冗长 | 读者放弃阅读 | 精简到必要内容 |
| 缺少目录 | 无法快速定位 | 添加目录和锚点 |
| 术语不一致 | 理解混乱 | 建立术语表 |