| name | document-writer |
| description | 文档写作技能,帮助撰写技术文档、API 文档、用户手册等 |
| category | document |
| tags | ["document","writing","technical","api","markdown"] |
文档写作技能
概述
这个技能帮助你撰写各类专业文档:
- 技术设计文档
- API 接口文档
- 用户使用手册
- README 文件
- 变更日志
文档类型模板
1. README 文件
# 项目名称
简短的项目描述(一两句话)
## 功能特性
- ✅ 特性一
- ✅ 特性二
- ✅ 特性三
## 快速开始
### 安装
```bash
npm install package-name
使用
import { something } from 'package-name';
配置
| 参数 | 类型 | 默认值 | 说明 |
|---|
| option1 | string | - | 描述 |
| option2 | number | 10 | 描述 |
API 文档
详见 API 文档
贡献指南
欢迎贡献!请阅读 贡献指南
许可证
MIT License
### 2. API 接口文档
```markdown
# API 接口文档
## 基础信息
- 基础 URL: `https://api.example.com/v1`
- 认证方式: Bearer Token
## 接口列表
### 获取用户信息
获取指定用户的详细信息。
**请求**
GET /users/{id}
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | string | 是 | 用户 ID |
**请求头**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| Authorization | string | 是 | Bearer {token} |
**响应**
```json
{
"code": 200,
"data": {
"id": "user_123",
"name": "张三",
"email": "zhangsan@example.com",
"created_at": "2024-01-01T00:00:00Z"
}
}
错误码
### 3. 技术设计文档
```markdown
# 技术设计文档
## 1. 概述
### 1.1 背景
[描述项目背景和需求来源]
### 1.2 目标
- 目标一
- 目标二
### 1.3 非目标
- 不在本次范围内的内容
## 2. 系统设计
### 2.1 架构图
[架构图]
### 2.2 核心组件
#### 组件 A
- 职责: [描述]
- 接口: [描述]
#### 组件 B
- 职责: [描述]
- 接口: [描述]
### 2.3 数据流
[描述数据如何在系统中流动]
## 3. 详细设计
### 3.1 数据模型
```sql
CREATE TABLE users (
id VARCHAR(36) PRIMARY KEY,
name VARCHAR(100) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
3.2 API 设计
[API 接口列表]
3.3 关键算法
[算法描述和伪代码]
4. 安全考虑
5. 性能考虑
6. 测试计划
7. 部署计划
8. 风险评估
### 4. 变更日志
```markdown
# 变更日志
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
## [未发布]
### 新增
- 新功能描述
### 变更
- 变更描述
### 修复
- Bug 修复描述
## [1.0.0] - 2024-01-01
### 新增
- 初始版本发布
- 核心功能 A
- 核心功能 B
### 安全
- 安全相关更新
写作原则
- 清晰简洁: 使用简单直接的语言
- 结构化: 使用标题、列表、表格组织内容
- 示例驱动: 提供具体的代码示例
- 保持更新: 文档应与代码同步更新
- 面向读者: 考虑读者的技术背景
常用 Markdown 语法
- 标题:
# ## ###
- 列表:
- * 1.
- 代码: ``
code
- 链接:
[text](url)
- 图片:

- 表格:
| col1 | col2 |
- 引用:
> quote
- 强调:
**bold** *italic*