You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
304 lines
6.6 KiB
304 lines
6.6 KiB
# 文档编写规范
|
|
|
|
## 📋 文档信息
|
|
|
|
- **文档版本**: v1.0.0
|
|
- **创建日期**: 2024年
|
|
- **最后更新**: 2024年
|
|
- **文档状态**: 草稿
|
|
- **维护人员**: 技术文档团队
|
|
|
|
## 🎯 规范概述
|
|
|
|
本文档规定了项目文档的编写标准，确保文档的一致性、可读性和可维护性。
|
|
|
|
## 📝 文档结构规范
|
|
|
|
### 标准文档结构
|
|
每个文档应包含以下标准结构：
|
|
|
|
```markdown
|
|
# 文档标题
|
|
|
|
## 📋 文档信息
|
|
- **文档版本**: v1.0.0
|
|
- **创建日期**: YYYY年MM月DD日
|
|
- **最后更新**: YYYY年MM月DD日
|
|
- **文档状态**: 草稿/审核中/已发布/已废弃
|
|
- **维护人员**: 负责人姓名
|
|
|
|
## 🎯 概述/目标
|
|
文档的主要内容和目标
|
|
|
|
## 📚 主要内容
|
|
文档的详细内容
|
|
|
|
## 📝 变更记录
|
|
| 版本 | 日期 | 变更内容 | 变更人 |
|
|
|------|------|----------|--------|
|
|
| v1.0.0 | YYYY-MM-DD | 初始版本 | 作者姓名 |
|
|
|
|
---
|
|
|
|
*如有疑问，请联系[负责人/团队]*
|
|
```
|
|
|
|
### 标题层级规范
|
|
- **一级标题**: 使用单个 `#`，文档主标题
|
|
- **二级标题**: 使用 `##`，主要章节
|
|
- **三级标题**: 使用 `###`，子章节
|
|
- **四级标题**: 使用 `####`，具体内容分组
|
|
- **五级标题**: 使用 `#####`，详细说明
|
|
- **六级标题**: 使用 `######`，最细粒度分组
|
|
|
|
## 🎨 格式规范
|
|
|
|
### 文本格式
|
|
```markdown
|
|
# 强调文本
|
|
**粗体文本** - 用于重要信息
|
|
*斜体文本* - 用于次要信息
|
|
`代码片段` - 用于代码、命令、文件名等
|
|
|
|
# 列表格式
|
|
- 无序列表项
|
|
- 另一个列表项
|
|
|
|
1. 有序列表项
|
|
2. 另一个有序列表项
|
|
|
|
# 引用
|
|
> 引用文本，用于引用外部内容或重要说明
|
|
|
|
# 分割线
|
|
---
|
|
```
|
|
|
|
### 代码块格式
|
|
```markdown
|
|
# 行内代码
|
|
使用 `npm install` 安装依赖
|
|
|
|
# 代码块
|
|
```javascript
|
|
function example() {
|
|
console.log('Hello World');
|
|
}
|
|
```
|
|
|
|
# 带语言标识的代码块
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
```
|
|
|
|
### 表格格式
|
|
```markdown
|
|
| 列标题1 | 列标题2 | 列标题3 |
|
|
|---------|---------|---------|
|
|
| 内容1 | 内容2 | 内容3 |
|
|
| 内容4 | 内容5 | 内容6 |
|
|
```
|
|
|
|
### 链接格式
|
|
```markdown
|
|
# 外部链接
|
|
[链接文本](https://example.com)
|
|
|
|
# 内部链接
|
|
[相关文档](./related-doc.md)
|
|
|
|
# 锚点链接
|
|
[跳转到章节](#章节名称)
|
|
```
|
|
|
|
## 🔤 语言规范
|
|
|
|
### 中文规范
|
|
- 使用简体中文
|
|
- 标点符号使用中文标点
|
|
- 数字和英文单词前后加空格
|
|
- 避免使用网络用语和缩写
|
|
|
|
### 英文规范
|
|
- 代码注释使用英文
|
|
- 技术术语保持英文原样
|
|
- 文件名、变量名使用英文
|
|
- API 接口名称使用英文
|
|
|
|
### 中英文混排
|
|
```markdown
|
|
# 正确示例
|
|
Vue.js 是一个渐进式 JavaScript 框架
|
|
使用 npm install 命令安装依赖
|
|
|
|
# 错误示例
|
|
Vue.js是一个渐进式JavaScript框架
|
|
使用npm install命令安装依赖
|
|
```
|
|
|
|
## 📊 图表规范
|
|
|
|
### 流程图
|
|
```markdown
|
|
```mermaid
|
|
graph TD
|
|
A[开始] --> B{判断条件}
|
|
B -->|是| C[执行操作]
|
|
B -->|否| D[结束]
|
|
C --> D
|
|
```
|
|
```
|
|
|
|
### 时序图
|
|
```markdown
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant 用户
|
|
participant 前端
|
|
participant 后端
|
|
participant 数据库
|
|
|
|
用户->>前端: 点击按钮
|
|
前端->>后端: 发送请求
|
|
后端->>数据库: 查询数据
|
|
数据库-->>后端: 返回结果
|
|
后端-->>前端: 响应数据
|
|
前端-->>用户: 显示结果
|
|
```
|
|
```
|
|
|
|
### 类图
|
|
```markdown
|
|
```mermaid
|
|
classDiagram
|
|
class User {
|
|
+String name
|
|
+String email
|
|
+login()
|
|
+logout()
|
|
}
|
|
|
|
class Role {
|
|
+String name
|
|
+String description
|
|
+checkPermission()
|
|
}
|
|
|
|
User --> Role
|
|
```
|
|
```
|
|
|
|
## 🔍 内容规范
|
|
|
|
### 技术文档
|
|
- 准确描述技术实现
|
|
- 提供完整的代码示例
|
|
- 说明配置参数和选项
|
|
- 包含错误处理和故障排除
|
|
|
|
### 用户文档
|
|
- 使用简单易懂的语言
|
|
- 提供步骤化的操作说明
|
|
- 包含截图和示例
|
|
- 说明常见问题和解决方案
|
|
|
|
### API 文档
|
|
- 详细说明接口参数
|
|
- 提供请求和响应示例
|
|
- 说明错误码和错误信息
|
|
- 包含接口调用示例
|
|
|
|
## 📱 文档类型规范
|
|
|
|
### 产品文档
|
|
- **需求文档**: 详细描述产品功能需求
|
|
- **设计文档**: 产品界面和交互设计
|
|
- **用户手册**: 用户操作指南
|
|
- **功能说明**: 功能特性介绍
|
|
|
|
### 技术文档
|
|
- **架构文档**: 系统架构设计
|
|
- **开发文档**: 开发环境搭建和规范
|
|
- **API 文档**: 接口接口说明
|
|
- **部署文档**: 部署和运维指南
|
|
|
|
### 管理文档
|
|
- **项目计划**: 项目时间安排和里程碑
|
|
- **会议纪要**: 重要会议记录
|
|
- **变更记录**: 项目变更历史
|
|
- **风险评估**: 项目风险分析
|
|
|
|
## 🔄 版本管理规范
|
|
|
|
### 版本号规则
|
|
- **主版本号**: 重大功能变更或架构调整
|
|
- **次版本号**: 新功能添加或重要修复
|
|
- **修订版本号**: 问题修复和小幅改进
|
|
|
|
### 文档状态
|
|
- **草稿**: 初始编写阶段
|
|
- **审核中**: 等待审核确认
|
|
- **已发布**: 正式发布使用
|
|
- **已废弃**: 不再维护的文档
|
|
|
|
### 变更记录
|
|
每次文档更新都应记录：
|
|
- 版本号
|
|
- 更新日期
|
|
- 变更内容
|
|
- 变更人
|
|
|
|
## 📋 模板使用
|
|
|
|
### 文档模板
|
|
项目提供标准文档模板，包括：
|
|
- 技术文档模板
|
|
- 用户文档模板
|
|
- API 文档模板
|
|
- 会议纪要模板
|
|
|
|
### 模板位置
|
|
```
|
|
docs/
|
|
├── templates/ # 文档模板
|
|
│ ├── technical.md # 技术文档模板
|
|
│ ├── user-guide.md # 用户指南模板
|
|
│ ├── api-doc.md # API 文档模板
|
|
│ └── meeting-notes.md # 会议纪要模板
|
|
└── standards/ # 规范文档
|
|
└── documentation-standards.md
|
|
```
|
|
|
|
## 🚀 最佳实践
|
|
|
|
### 编写建议
|
|
1. **明确目标读者**: 根据读者水平调整内容深度
|
|
2. **结构清晰**: 使用合理的标题层级组织内容
|
|
3. **内容准确**: 确保技术信息的准确性
|
|
4. **示例丰富**: 提供足够的代码和操作示例
|
|
5. **及时更新**: 保持文档与代码的同步
|
|
|
|
### 审核流程
|
|
1. **自检**: 作者完成初稿后进行自我检查
|
|
2. **同行评审**: 邀请同事进行技术评审
|
|
3. **专家审核**: 重要文档邀请专家审核
|
|
4. **发布确认**: 最终确认后发布文档
|
|
|
|
### 维护建议
|
|
1. **定期检查**: 定期检查文档的准确性
|
|
2. **用户反馈**: 收集用户对文档的反馈
|
|
3. **版本同步**: 确保文档与产品版本同步
|
|
4. **持续改进**: 根据反馈持续改进文档质量
|
|
|
|
## 📝 变更记录
|
|
|
|
| 版本 | 日期 | 变更内容 | 变更人 |
|
|
|------|------|----------|--------|
|
|
| v1.0.0 | 2024年 | 初始版本 | 技术文档团队 |
|
|
|
|
---
|
|
|
|
*如有疑问，请联系技术文档团队*
|