项目开发维护｜文档规范

1. 文档规范

文档是项目中很重要的组成部分，没有文档的项目很难理解、部署和使用。因此，编写文档是一个必不可少的开发工作。一个项目中最需要的 3 类文档是 README 文档、项目文档和 API 接口文档。

1.1. README 文档

README 文档是项目的门面，它是开发者学习项目时第一个阅读的文档，会放在项目的根目录下。它主要用来介绍项目的功能、安装、部署和使用。

READM 规范中的内容如下所示。有一个在线的 README 生成工具，叫做 readme.so 可以参考下。


# 项目名称

<!-- 写一段简短的话描述项目 -->

## 功能特性

<!-- 描述该项目的核心功能点 -->

## 软件架构(可选)

<!-- 可以描述下项目的架构 -->

## 快速开始

### 依赖检查

<!-- 描述该项目的依赖，比如依赖的包、工具或者其他任何依赖项 -->

### 构建

<!-- 描述如何构建该项目 -->

### 运行

<!-- 描述如何运行该项目 -->

## 使用指南

<!-- 描述如何使用该项目 -->

## 如何贡献

<!-- 告诉其他开发者如果给该项目贡献源码 -->

## 社区(可选)

<!-- 如果有需要可以介绍一些社区相关的内容 -->

## 关于作者

<!-- 这里写上项目作者 -->

## 谁在用(可选)

<!-- 可以列出使用本项目的其他有影响力的项目，算是给项目打个广告吧 -->

## 许可证

<!-- 这里链接上该项目的开源许可证 -->

一个实际的例子如下所示：

# IAM - 身份识别与访问管理系统

IAM = Identity and Access Management

IAM 是一个基于 Go 语言开发的身份识别与访问管理系统，用于对资源访问进行授权。同时也具有如下能力：

1. 配合极客时间专栏 **《[Go 语言项目开发实战](https://time.geekbang.org/column/intro/100079601)》**，讲解如何用 Go 做企业级应用的开发，是该项目的理论课程，包含了项目各个知识点和构建思路的讲解，也会包含我的一线研发经验和建议。

   目录请参考：[《Go 语言项目开发实战》课程目录](./docs/guide/zh-CN/geekbang/geekbang_course_catalog.md)


2. 作为一个开发脚手架，供开发者克隆后二次开发，快速构建自己的应用。

IAM 项目会长期维护、定期更新，**欢迎兄弟们 Star & Contributing**

## 功能特性

本项目用到了Go企业开发的大部分核心技能点，见下图：

![技术思维导图](./docs/images/技术思维导图.png)

更多请参考：[marmotedu/gocollect](https://github.com/marmotedu/gocollect)

## 软件架构

![IAM架构](./docs/images/IAM架构.png)

架构解析见：[IAM 架构 & 能力说明](docs/guide/zh-CN/installation/installation-architecture.md)

## 快速开始

### 依赖检查

**Minimum Requirements**

- Hardware
  - 2 GB of Memory
  - 50 GB of Disk Space
- 操作系统：CentOS Linux 8.2 (64-bit)
- 正常访问外网

 **需求检查 & 依赖安装** 

 请参考：[](docs/guide/zh-CN/installation/installation-requirement.md)

### 构建

1. 代码包下载

```
$ git clone https://github.com/marmotedu/iam
```

2. 编译

```bash
$ cd iam
$ make
```

### 运行

```bash
./scripts/install/install.sh iam::install::install_iam    
```

## 使用指南

[IAM Documentation](docs/guide/zh-CN)

## 如何贡献

欢迎贡献代码，贡献流程可以参考 [developer's documentation](docs/devel/zh-CN/development.md)。

## 社区

You are encouraged to communicate most things via [GitHub issues](https://github.com/marmotedu/iam/issues/new/choose) or pull requests.

## 关于作者

- Lingfei Kong <colin404@foxmail.com>

为了方便交流，我建了微信群，可以加我 **微信：nightskong**，拉你入群，方便交流。

## 谁在用

如果你有项目在使用iam系统模板，也欢迎联系作者，加入使用案例。

## 许可证

IAM is licensed under the MIT. See [LICENSE](LICENSE) for the full license text.

1.2. 项目文档

项目文档包括了一切需要文档化的内容，通常集中放在 /docs 目录下。好的文档规范有两个优点：易读和可以快速定位文档。不同项目有不同的文档需求，但是一般都会考虑以下两类文档：

开发文档：用来说明该项目的开发流程，比如如何搭建开发环境、构建二进制文件、测试、部署等。
用户文档：软件的使用文档，对象一般是软件的使用者，内容可根据需要添加。比如，可以包含 API 文档、SDK 文档、安装文档、功能介绍文档、最佳实践、操作指南、常见问题等。

为了方便全球开发者和用户使用，开发文档和用户文档，可以预先规划好英文和中文两个版本。

下面是一个项目文档的示例：


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.3. API 文档

接口文档又称为 API 文档，一般由后台开发人员编写，用来描述组件提供的 API 接口，以及如何调用这些 API 接口。

在项目初期，接口文档可以解耦前后端，前后端并行开发：前端只需要按照接口文档实现调用逻辑，后端只需要按照接口文档提供功能。

当前后端都开发完成之后，我们就可以直接进行联调，提高开发效率。在项目后期，API 文档可以提供给使用者，不仅可以降低组件的使用门槛，还能够减少沟通成本。

1.3.1. API 文档编写方式

API 文档有四种编写方式，包括编写 word 格式文档、借助工具编写、通过注释生成和编写 Markdown 格式文档。具体实现如下所示：

其中，通过注释生成和编写 Markdown 格式文档这 2 种方式用得最多。推荐使用 Markdown 格式文档的方式，原因如下：

相比通过注释生成的方式，编写 Markdown 格式的接口文档，能表达更丰富的内容和格式，不需要在代码中添加大量注释。
相比 Word 格式的文档，Markdown 格式文档占用的空间更小，能够跟随代码仓库一起发布，方便 API 文档的分发和查找。
相比在线 API 文档编写工具，Markdown 格式的文档免去了第三方平台依赖和网络的限制。

1.4. API 文档规范

一个规范的 API 接口文档，通常需要包含一个完整的 API 接口介绍文档、API 接口变更历史文档、通用说明、数据结构说明、错误码描述和 API 接口使用文档（API 接口使用文档中需要包含接口描述、请求方法、请求参数、输出参数和请求示例）。

当然，根据不同的项目需要，API 接口文档会有不同的格式和内容。一个 API 接口文档示例如下所示，被拆分成若干个 markdown 文件，并放在 docs/guide/zh-CN/api 中。

README.md ：API 接口介绍文档，会分类介绍支持的 API 接口，并会存放相关 API 接口文档的链接，方便开发者查看。
CHANGELOG.md ：API 接口文档变更历史，方便进行历史回溯，也可以使调用者决定是否进行功能更新和版本更新。
generic.md ：用来说明通用的请求参数、返回参数、认证方法和请求方法等。
struct.md ：用来列出接口文档中使用的数据结构。这些数据结构可能被多个 API 接口使用，会在 user.md、secret.md、policy.md 文件中被引用。
user.md 、 secret.md 、 policy.md ：API 接口使用文档，相同 REST 资源的接口会存放在一个文件中，以 REST 资源名命名文档名。

下面以 user.md 接口使用文档为例解释接口使用文档是怎么写的。user.md 这个文件中记录了 user 相关的接口，每个接口按照顺序排列：
- 接口描述：描述接口实现了什么功能。
- 请求方法：接口的请求方法，格式为 HTTP 方法请求路径，例如 POST /v1/users。在通用说明中的请求方法部分，会说明接口的请求协议和请求地址。
- 输入参数：接口的输入字段，它又分为 Header 参数、Query 参数、Body 参数、Path 参数。每个字段通过：参数名称、必选、类型和描述 4 个属性来描述。如果参数有限制或者默认值，可以在描述部分注明。
- 输出参数：接口的返回字段，每个字段通过参数名称、类型和描述 3 个属性来描述。
- 请求示例：一个真实的 API 接口请求和返回示例。
error_code.md ：错误码描述，通过程序自动生成。

更详细的 API 接口文档规范，可参考这个链接：https://github.com/dawnguodev/iam/tree/master/docs/guide/zh-CN/api

1.5. 资料

在线的 README 生成工具，readme.so；
proto 自动生成 API 文档；
coding API 文档工具或者 yapi；

2. 巨人的肩膀

极客时间.孔令飞.《Go 语言项目开发实战》