项目规范
hexiaopi 1/24/2020 规范项目
README文档是项目的门面，通过README文档可以帮助用户快速了解项目。
README文档可以参考以下模板，或者通过在线网站生成readme.so (opens new window)
# 项目名称
<!-- 简介项目 -->
## 功能特性
<!-- 描述该项目的核心功能点 -->
## 软件架构(可选)
<!-- 描述下项目的架构 -->
## 快速开始
### 依赖检查
<!-- 该项目的依赖，比如依赖的包、工具或者其他任何依赖项 -->
### 构建
<!-- 如何构建该项目 -->
### 运行
<!-- 如何运行该项目 -->
### 预览环境（可选）
<!-- 提供预览环境，帮助用户快速尝鲜 -->
## 使用指南
<!-- 如何使用该项目 -->
## 如何贡献
<!-- 如何贡献源码 -->
## 社区(可选)
<!-- 社区相关的内容 -->
## 关于作者
<!-- 项目作者(多个) -->
## 谁在用(可选)
<!-- 使用本项目的其他有影响力的项目，加分 -->
## 许可证
<!-- 开源许可证 -->
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
项目文档通常放在
/docs目录下。包含：开发文档 面向开发人员，用来说明开发流程、构建、测试、部署等。
用户文档 面向使用人员，包括：API文档、SDK文档、安装文档、功能介绍文档、最佳实践、操作指南、常见问题等。
这里参考IAM (opens new window)项目的文档结构
docs
├── devel # 开发文档，可以提前规划好，英文版文档和中文版文档
│ ├── en-US/ # 英文版文档，可以根据需要组织文件结构
│ └── zh-CN # 中文版文档，可以根据需要组织文件结构
│ └── development.md # 开发手册，可以说明如何编译、构建、运行项目
├── guide # 用户文档
│ ├── en-US/ # 英文版文档，可以根据需要组织文件结构
│ └── zh-CN # 中文版文档，可以根据需要组织文件结构
│ ├── api/ # API文档
│ ├── best-practice # 最佳实践，存放一些比较重要的实践文章
│ │ └── authorization.md
│ ├── faq # 常见问题
│ │ ├── iam-apiserver
│ │ └── installation
│ ├── installation # 安装文档
│ │ └── installation.md
│ ├── introduction/ # 产品介绍文档
│ ├── operation-guide # 操作指南，里面可以根据RESTful资源再划分为更细的子目录，用来存放系统核心/全部功能的操作手册
│ │ ├── policy.md
│ │ ├── secret.md
│ │ └── user.md
│ ├── quickstart # 快速入门
│ │ └── quickstart.md
│ ├── README.md # 用户文档入口文件
│ └── sdk # SDK文档
│ └── golang.md
└── images # 图片存放目录
└── 部署架构v1.png
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
