DOCUMENTATION_STANDARDS.md 9.07 KB

Raw Blame History Permalink



📖 文档编写规范

本文档定义了项目中编写和维护文档的标准规范，确保文档质量、一致性和可维护性。


📑 目录


文档分类规则
文件命名规范
文档结构模板
Markdown 编写规范
文档更新流程
审查与发布


文档分类规则

所有文档必须放在对应分类目录下：

docs/
├── architecture/   # 🏗️ 架构设计类
├── development/    # 💻 开发配置类
├── testing/        # 🧪 测试文档类
├── tools/          # 🛠️ 工具指南类
├── tasks/          # 📋 任务管理类
│   ├── done/       # 已完成任务
│   ├── plan/       # 计划中任务
│   └── todo/       # 待办事项
├── CHANGELOG.md    # 📝 变更记录（根目录）
└── README.md       # 📚 文档导航索引（根目录）


如何选择分类


如果文档是关于...
放在...


系统架构、组件设计、目录结构
architecture/


开发工具配置、代码规范、Git Hooks
development/


测试框架、测试指南、测试配置
testing/


外部工具使用指南（如 Claude Skills）
tools/


任务、计划、待办事项
tasks/


版本更新历史

CHANGELOG.md（根目录）


文件命名规范


基本规则


使用英文命名


✅ ARCHITECTURE.md

❌ 架构文档.md


使用大写字母和下划线


✅ E2E_AUTH_GUIDE.md

❌ e2e-auth-guide.md


名称清晰描述内容


✅ ESLINT_PRETTIER.md

❌ CODE_STYLE.md


避免空格和特殊字符


✅ WORKFLOW.md

❌ 工作流.md


任务文档命名

格式：[日期]_[类型]_[简短描述].md


类型标识
说明
示例


feature
新功能
20260128_feature_打卡草稿缓存.md


bugfix
Bug 修复
20260128_bugfix_视频播放器修复.md


optimize
性能优化
20260128_optimize_首页加载优化.md


refactor
代码重构
20260128_refactor_组件拆分.md


docs
文档更新
20260128_docs_API文档补充.md


config
配置变更
20260128_config_Vite配置优化.md


文档结构模板


标准模板

每个文档应遵循以下结构：

# 文档标题

> 一句话描述文档的用途和目标读者

**作者**: [可选]
**创建日期**: YYYY-MM-DD
**最后更新**: YYYY-MM-DD
**状态**: [草稿/审阅中/已发布]

---

## 📑 目录

- [背景](#背景)
- [安装/配置](#安装配置)
- [使用指南](#使用指南)
- [API/配置](#api配置)
- [示例](#示例)
- [常见问题](#常见问题)
- [相关资源](#相关资源)

---

## 背景

说明文档的背景、目的和适用场景。

---

## 安装/配置

### 前置条件

列出所需的工具、环境等。

### 步骤

1. 第一步
2. 第二步
3. 第三步

---

## 使用指南

### 基础用法

```javascript
// 代码示例
代码块


### 高级用法

高级使用场景和技巧。

---

## API/配置

### 配置项

| 参数   | 类型   | 默认值    | 说明     |
| ------ | ------ | --------- | -------- |
| param1 | string | 'default' | 参数说明 |

### 方法

```typescript
function example(param: string): void {
  // 实现
}


示例


示例 1：场景描述

# 命令示例
command


示例 2：场景描述

// 代码示例
code


常见问题


Q: 问题标题？

A: 答案说明。


Q: 另一个问题？

A: 答案说明。


相关资源


相关文档1
相关文档2
外部资源


---

## Markdown 编写规范

### 标题层级

```markdown
# H1 - 文档标题（每个文档只有一个）
## H2 - 主要章节
### H3 - 子章节
#### H4 - 四级标题（避免更深）


规则:


H1 只用于文档标题
H2 用于主要章节
H3 用于子章节
避免超过 H4


代码块

使用 ``` 语言标识 指定语言：

\```javascript
// JavaScript 代码
\```

\```bash

# Bash 命令

\```

\```vue

<!-- Vue 组件 -->
<template>
  <div />
</template>
\```


支持的语法高亮：


javascript / js


typescript / ts

vue

bash / sh

json

yaml / yml


markdown / md


列表

无序列表:

- 项目 1
- 项目 2
  - 子项目 2.1
  - 子项目 2.2


有序列表:

1. 第一步
2. 第二步
3. 第三步


表格

| 列1   | 列2   | 列3   |
| ----- | ----- | ----- |
| 数据1 | 数据2 | 数据3 |


强调

**粗体文本**
_斜体文本_
**_粗斜体_**
`行内代码`


链接

[链接文本](./path/to/file.md)
[外部链接](https://example.com)
[带标题的链接](https://example.com '鼠标悬停提示')


图片

![图片描述](./path/to/image.png)
![图片描述](./path/to/image.png '图片标题')


引用

> 普通引用
>
> **引用中可以加粗**
> 可以多行


分隔线

---


任务列表

- [x] 已完成任务
- [ ] 待完成任务


Emoji

适当使用 emoji 增强可读性：


Emoji
用途


📚
文档


💻
代码/开发


🧪
测试


🏗️
架构


🛠️
工具


✅
完成/正确


❌
错误/避免


⚠️
警告


💡
建议/提示


📝
笔记/记录


文档更新流程


1. 新增文档

# 1. 在对应分类下创建文档
cd docs/architecture
vim NEW_DOC.md

# 2. 使用模板初始化
cp ../TEMPLATES/STANDARD.md NEW_DOC.md

# 3. 更新索引
# 编辑 ../README.md，在对应分类下添加链接


2. 更新文档

# 1. 修改文档内容
vim docs/xxx/FILE.md

# 2. 更新"最后更新"日期
# 在文档头部更新日期字段

# 3. 如果有重大变更，更新 CHANGELOG.md


3. 移动/删除文档

# 移动文档
git mv docs/old/FILE.md docs/new/FILE.md

# 删除文档（需谨慎）
git rm docs/xxx/FILE.md


4. 索引维护

每次新增或移动文档后，必须更新 docs/README.md：


在对应分类下添加或更新链接
如果是任务文档，更新 tasks/README.md

更新"快速查找"部分（如果适用）


审查与发布


自查清单

发布文档前，确认：


 文档放在正确的分类目录

 文件名遵循命名规范

 使用标准文档结构模板

 代码块指定了语言标识

 所有链接有效（可点击测试）

 更新了相关索引（README.md）

 添加了创建和更新日期

 拼写和语法检查通过


PR 审查

提交文档 PR 时：


标题格式: docs(category): 简短描述


   docs(testing): 添加 Playwright E2E 测试指南
   docs(architecture): 更新组件索引文档


描述内容:


新增或修改的内容
影响的文档
相关的 Issue 或 PR


审查重点:


文档分类是否正确
内容是否准确完整
链接是否有效
格式是否统一


发布检查

合并 PR 前确认：


 至少一人审查通过

 CI 检查通过（如果有）

 文档索引已更新

 相关文档已同步更新


特殊文档规范


CHANGELOG.md

遵循 Keep a Changelog 格式：

# 更新日志

## [Unreleased]

### Added

- 新功能 1
- 新功能 2

### Changed

- 变更 1

### Fixed

- 修复 1

## [1.2.0] - 2026-01-28

### Added

- 新功能


README.md


简洁明了，突出重点
包含项目简介和快速开始
提供清晰的文档导航


API 文档


使用表格展示参数
提供代码示例
说明返回值和错误码


💡 最佳实践


1. 保持简洁


❌ 避免冗长描述
✅ 用代码示例说话
✅ 适当使用图表和截图


2. 及时更新


代码变更时同步更新文档
标注"最后更新"日期
过时文档及时归档


3. 面向读者


明确文档的目标读者
提供不同深度的内容（入门/进阶）
使用场景驱动的示例


4. 可维护性


避免重复内容
使用引用和链接
保持统一的格式


5. 可搜索性


使用关键词
提供清晰的目录
添加元数据标签


🔗 相关资源


Markdown 指南
文档驱动开发
技术文档最佳实践


最后更新: 2026-01-28