lynn
/
Getinge-web
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
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.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '89174d54f4'
${ noResults }
Getinge-web/docs/standards/documentation-standards.md

6.6 KiB
Raw Blame History

文档编写规范

📋 文档信息

  • 文档版本: v1.0.0
  • 创建日期: 2024年
  • 最后更新: 2024年
  • 文档状态: 草稿
  • 维护人员: 技术文档团队

🎯 规范概述

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

📝 文档结构规范

标准文档结构

每个文档应包含以下标准结构：

# 文档标题

## 📋 文档信息
- **文档版本**: v1.0.0
- **创建日期**: YYYY年MM月DD日
- **最后更新**: YYYY年MM月DD日
- **文档状态**: 草稿/审核中/已发布/已废弃
- **维护人员**: 负责人姓名

## 🎯 概述/目标
文档的主要内容和目标

## 📚 主要内容
文档的详细内容

## 📝 变更记录
| 版本 | 日期 | 变更内容 | 变更人 |
|------|------|----------|--------|
| v1.0.0 | YYYY-MM-DD | 初始版本 | 作者姓名 |

---

*如有疑问，请联系[负责人/团队]*

标题层级规范

  • 一级标题: 使用单个 #，文档主标题
  • 二级标题: 使用 ##，主要章节
  • 三级标题: 使用 ###，子章节
  • 四级标题: 使用 ####，具体内容分组
  • 五级标题: 使用 #####，详细说明
  • 六级标题: 使用 ######，最细粒度分组

🎨 格式规范

文本格式

# 强调文本
**粗体文本** - 用于重要信息
*斜体文本* - 用于次要信息
`代码片段` - 用于代码、命令、文件名等

# 列表格式
- 无序列表项
- 另一个列表项

1. 有序列表项
2. 另一个有序列表项

# 引用
> 引用文本，用于引用外部内容或重要说明

# 分割线
---

代码块格式

# 行内代码
使用 `npm install` 安装依赖

# 代码块
```javascript
function example() {
  console.log('Hello World');
}

带语言标识的代码块

npm install
npm run dev


### 表格格式
```markdown
| 列标题1 | 列标题2 | 列标题3 |
|---------|---------|---------|
| 内容1   | 内容2   | 内容3   |
| 内容4   | 内容5   | 内容6   |

链接格式

# 外部链接
[链接文本](https://example.com)

# 内部链接
[相关文档](./related-doc.md)

# 锚点链接
[跳转到章节](#章节名称)

🔤 语言规范

中文规范

  • 使用简体中文
  • 标点符号使用中文标点
  • 数字和英文单词前后加空格
  • 避免使用网络用语和缩写

英文规范

  • 代码注释使用英文
  • 技术术语保持英文原样
  • 文件名、变量名使用英文
  • API 接口名称使用英文

中英文混排

# 正确示例
Vue.js 是一个渐进式 JavaScript 框架
使用 npm install 命令安装依赖

# 错误示例
Vue.js是一个渐进式JavaScript框架
使用npm install命令安装依赖

📊 图表规范

流程图

```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年 | 初始版本 | 技术文档团队 |

---

*如有疑问，请联系技术文档团队*