写出优秀技术文档

优秀 README 的结构

一个好的 README 应该让陌生人在 5 分钟内理解项目、能够运行起来，并知道如何贡献。

# 项目名称

> 一句话描述项目的核心价值

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/user/repo/workflows/CI/badge.svg)](https://github.com/user/repo/actions)

## ✨ 功能特性

- 特性一：简要描述
- 特性二：简要描述
- 特性三：简要描述

## 🚀 快速开始

### 安装

```bash
npm install your-package
```

### 基础用法

```javascript
const pkg = require('your-package')
pkg.doSomething()
```

## 📖 文档

完整文档请访问 [docs.example.com](https://docs.example.com)

## 🤝 贡献指南

请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)

## 📄 许可证

MIT License — 详见 [LICENSE](LICENSE)

API 文档模板

每个 API 端点/函数/方法应该包含：

## `functionName(param1, param2)`

**功能说明**：简要描述这个函数做什么。

### 参数

| 参数     | 类型   | 必填 | 说明           |
| -------- | ------ | :--: | -------------- |
| param1   | string |  ✅  | 用户唯一标识符 |
| param2   | number |  ❌  | 超时时间（毫秒），默认 5000 |

### 返回值

返回 `Promise<User>` 对象：

```typescript
interface User {
  id: string
  name: string
  email: string
}
```

### 示例

```javascript
const user = await getUser('user-123', 3000)
console.log(user.name)  // 'Alice'
```

### 错误处理

| 错误码 | 描述            |
| ------ | --------------- |
| 404    | 用户不存在      |
| 401    | 未授权          |

写作规范

1. 标题层级

• 每个文档只有一个 H1，用作文档标题
• H2 用于主要章节；H3 用于子章节；尽量避免 H4+
• 标题要能独立理解，不要用 "介绍"/"说明" 这类空洞标题

2. 段落长度

• 每段聚焦一个主题
• 技术文档段落不要超过 5-6 行
• 复杂的操作步骤用有序列表，而不是长段落

3. 代码示例

• 所有代码示例必须可以运行（经过验证）
• 始终标注语言（```python 而不是 ```）
• 复杂示例要加注释解释关键行
• 示例要完整，不要省略 import 等必要前提

4. 中文写作规范

• 中英文之间加空格：使用 JavaScript 开发（不要 使用JavaScript开发）
• 中文与数字之间加空格：共 10 个章节
• 专有名词保持原有大小写：GitHub、macOS、iOS
• 全角标点用于中文句子；代码和路径用半角

Markdown Lint

markdownlint 工具可以检查常见的 Markdown 格式问题：

# 安装
npm install -g markdownlint-cli

# 检查文件
markdownlint README.md
markdownlint docs/**/*.md

# 创建配置文件 .markdownlint.json

{
  "MD013": false,           // 不限制行长度
  "MD033": false,           // 允许内嵌 HTML
  "MD041": true,            // 要求第一行是 H1
  "MD022": true,            // 标题前后要有空行
  "MD024": false            // 允许重复标题（API 文档常见）
}

版本化文档策略

在 README 中标注版本

> **注意**：本文档适用于 v2.x。[查看 v1.x 文档](./docs/v1/README.md)

## 安装

```bash
npm install my-pkg@2.0.0
```

CHANGELOG 格式（Keep a Changelog）

# 更新日志

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

## [未发布]

## [2.1.0] - 2026-03-26

### 新增
- 添加 TypeScript 类型定义
- 支持 Node.js 20+

### 修复
- 修复大文件上传时的内存泄漏问题

### 废弃
- `oldMethod()` 将在 3.0 中移除，请使用 `newMethod()`

课程总结

恭喜完成 Markdown 完全指南！你现在掌握了：

• CommonMark 基础语法：标题、段落、列表、链接、图片、代码
• GFM 扩展：表格、任务列表、删除线、告警块
• 高级功能：Mermaid 图表、LaTeX 数学公式、内嵌 HTML
• 完整工具链：VS Code、Pandoc、MkDocs、Docusaurus、Obsidian
• 写出优秀技术文档的规范与最佳实践