document-writer

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": "[e-mail]",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

错误码

错误码	说明
404	用户不存在
401	未授权

### 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. 性能考虑

• 预期 QPS
• 响应时间要求
• 扩展性设计

6. 测试计划

• 单元测试
• 集成测试
• 性能测试

7. 部署计划

• 部署步骤
• 回滚方案

8. 风险评估

风险	影响	缓解措施
风险一	高	措施

### 4. 变更日志

```markdown
# 变更日志

本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [未发布]

### 新增
- 新功能描述

### 变更
- 变更描述

### 修复
- Bug 修复描述

## [1.0.0] - 2024-01-01

### 新增
- 初始版本发布
- 核心功能 A
- 核心功能 B

### 安全
- 安全相关更新

写作原则

1. 清晰简洁: 使用简单直接的语言
2. 结构化: 使用标题、列表、表格组织内容
3. 示例驱动: 提供具体的代码示例
4. 保持更新: 文档应与代码同步更新
5. 面向读者: 考虑读者的技术背景

常用 Markdown 语法

• 标题: # ## ###
• 列表: - * 1.
• 代码: `` code
• 链接: [text](url)
• 图片: ![alt](url)
• 表格: | col1 | col2 |
• 引用: > quote
• 强调: **bold** *italic*