一位CTO告诉我，项目中至少需要这3类文档

Posted 2021-05-18 程序新视界

前言

在项目管理中，不可避免的会涉及到技术文档。当讨论文档时往往会纠结于“要”还是“不要”这种是非选择中。而忽略了，如何最小化技术文档的同时，又能体现出文档的价值。

看到了一位CTO写的文章，才发现，我们讨论的出发点可能就错了。在我们习以为常当中，很多项目已经为我们展示了文档的魅力。

为了让开发人员快速的了解一个项目，帮助新加入者快速接手，项目中通常需要提供这三类文档：README文档、架构文档和API文档。下面逐一展开聊聊它们通常包含哪些内容。

README文档

看看GitHub上的开源项目，基于上都包含了一个README.md的文件，它就是README文档。这也是在GitHub上创建项目时会默认创建的一个文件。

这也是阅读源代码时第一个看到的文档。如果你的项目中还没有README文档，或者文档的内容为空，你需要反思一下了。通过README文档，可以方便的为团队成员或未来要加入信任描述这个项目的构成及基本操作。

README文档中通常会包含以下内容：

• 高层面的概述，至少用3到4句话来介绍这个项目的用途；
• 项目的CI和质量保障；
• 运行要求，比如编程语言、工具、环境配置等；
• 构建说明；
• 本地运行指令。通常包括，每一步执行命令的说明或基于docker容器的运行。
• 配置说明。开发人员需要了解的关键配置说明，比如，修改端口号等。
• 相关联的重要服务。比如，CI服务（Jenkins、GitHub等）、项目管理工具（JIRA等）、原型工具等。

以开源框架Nacos为例，它的READM文档部分内容如下：

很显然，最开始告诉我们Nacos这款开源框架能够做什么，能够提供什么功能。

说明如何去做，如何启动部署。

紧接着是关联项目、文档、相关资源库等。

通过上面的说明，我们基本上知道Nacos是用来干什么的，怎么一步步操作，然后相关的资料、文档、类库等怎么查找。很简单的一个文档，却能够对使用者或开发者提供很有效的帮助。

架构文档

架构文档通常从系统架构层面来描述项目的，以便于任何想了解项目技术细节和架构体系的人进行查看。架构文档，通常涵盖了那些不会经常变动的架构和细节。

针对架构文档，通常包含以下内容：

• 约束条件。设计系统时遇到的任何业务或技术约束项，并指出这些约束如何影响到了系统设计；
• 非功能性要求。达到业务目标所需的最重要的质量指标；
• 架构设计。基于质量指标，哪些架构设计可以满足；
• 解决方案上下文图。将系统实现作为黑匣子，主要展示用户角色和外部集成与系统直接的关系；
• 解决方案容器图。展示系统架构中是有哪些组件构成，组件之间有什么样的关系，还要展示出它们依赖的类库还是服务；
• 技术栈及版本信息。展示用于构建系统的核心技术栈及版本信息，以及选择使用它们的原因。

文档也是项目的一部分，也应该像代码一样进行审查和迭代。关于架构图这里推荐Draw.io这款开源的画图工具。

关于架构文档，这里看一个名叫JetLinks的物联网开源项目的架构图：

看了这个项目提供架构和设备接入流程图，是不是一下子就从宏观上了解了这个系统的架构和功能了？如果我们的系统同样提供类似的架构文档，无论是编写者自己（过一段时间也会遗忘）还是其他协作者、新加入者来说，都是极大的福利。

API文档

关于API文档，这个不用多说，无论是前后端分离项目，还是对外提供接口的项目，API文档都是必不可少的。目前大多数项目都采用基于Swagger的REST API。Swagger是基于YAML或JSON格式展示，也可以在线浏览。如果你想更方便的阅读离线文档，可使用swagger-markdown这款插件生成基于markdown格式的文档。

Swagger的在线文档我们都知道，如果导出为离线文档，效果类似下图：

是不是比在线的看起来更加舒服，更加方便。关键是查看文档的时候不用再启动服务了。

小结

好的文档，可以让项目走的更加长远，可以让新加入的成员更快速的了解系统的架构与设计。对于开发者自己来说，也可以通过阅读文档来节省时间。建议每经过三四个功能迭代之后，花半天时间更新一下文档，这将为团队提供长期的效益。作为团队的管理者或参与者，上面讲的三类文档，都值得你思考，值得你推行。

---

程序新视界
公众号“ 程序新视界”，一个让你软实力、硬技术同步提升的平台，提供海量资料