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

简介: 一位CTO告诉我,项目中至少需要这3类文档

前言

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

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

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

README文档

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

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

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

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

以开源框架Nacos为例,它的READM文档部分内容如下: image.png很显然,最开始告诉我们Nacos这款开源框架能够做什么,能够提供什么功能。

image.png说明如何去做,如何启动部署。

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

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

架构文档

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

针对架构文档,通常包含以下内容:

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

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

关于架构文档,这里看一个名叫JetLinks的物联网开源项目的架构图:image.pngimage.png看了这个项目提供架构和设备接入流程图,是不是一下子就从宏观上了解了这个系统的架构和功能了?如果我们的系统同样提供类似的架构文档,无论是编写者自己(过一段时间也会遗忘)还是其他协作者、新加入者来说,都是极大的福利。

API文档

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

Swagger的在线文档我们都知道,如果导出为离线文档,效果类似下图:image.png是不是比在线的看起来更加舒服,更加方便。关键是查看文档的时候不用再启动服务了。

小结

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

目录
相关文章
|
前端开发 JavaScript Java
Layui之入门
Layui之入门
303 0
|
6月前
|
前端开发 安全 Java
Spring Boot 便利店销售系统项目分包设计解析
本文深入解析了基于Spring Boot的便利店销售系统分包设计,通过清晰的分层架构(表现层、业务逻辑层、数据访问层等)和模块化设计,提升了代码的可维护性、复用性和扩展性。具体分包结构包括`controller`、`service`、`repository`、`entity`、`dto`、`config`和`util`等模块,职责分明,便于团队协作与功能迭代。该设计为复杂企业级应用开发提供了实践参考。
231 0
|
机器学习/深度学习 存储 测试技术
【YOLOv10改进-注意力机制】iRMB: 倒置残差移动块 (论文笔记+引入代码)
YOLOv10专栏介绍了融合CNN与Transformer的iRMB模块,用于轻量级模型设计。iRMB在保持高效的同时结合了局部和全局信息处理,减少了资源消耗,提升了移动端性能。在ImageNet等基准上超越SOTA,且在目标检测等任务中表现优秀。代码示例展示了iRMB的实现细节,包括自注意力机制和卷积操作的整合。更多配置信息见相关链接。
|
10月前
|
存储 网络协议 Windows
AD域备份和恢复工具
RecoveryManager Plus 是一款强大的Active Directory备份和恢复工具,弥补了Microsoft本地AD功能的不足。它不仅支持对象级和属性级的备份与还原,还能备份架构属性、组成员信息和Exchange属性等关键元素。通过简单的鼠标点击,即可恢复已删除的对象或回滚整个AD到先前状态。该工具还提供定期完整备份、增量备份、备份保留策略等功能,确保AD环境的安全性和可恢复性。此外,它支持免重启恢复,适用于多种Windows服务器版本,是保护AD环境的理想选择。
192 5
|
11月前
|
Kubernetes Linux Docker
容器化技术Docker入门与实践
容器化技术Docker入门与实践
178 20
|
JavaScript 前端开发
Bugku CTF web 你必须让他停下来 解题思路
Bugku CTF web 你必须让他停下来 解题思路
227 2
|
机器学习/深度学习 存储 安全
基于YOLOv8深度学习的人脸面部口罩检测系统【python源码+Pyqt5界面+数据集+训练代码】目标检测
基于YOLOv8深度学习的人脸面部口罩检测系统【python源码+Pyqt5界面+数据集+训练代码】目标检测
|
存储
【计算机组成原理】指令系统
【计算机组成原理】指令系统
734 0
【计算机组成原理】指令系统
|
弹性计算 大数据 测试技术
阿里云服务器2核2G服务器多少钱?阿里云服务器2核2G服务器测评
阿里云服务器2核2G的价格根据配置和促销活动会有所不同。在2024年3月1日的降价政策之前,该服务器的价格可能为99元/年。然而,降价政策实施后,其价格可能会有所调整。具体的价格信息,建议前往阿里云官网查询。 关于阿里云服务器2核2G的测评,该服务器在性能上可以满足日常的网站搭建、应用开发等任务。它配备了2核CPU和2G内存,以及40G ESSD Entry云盘作为系统盘,可以保证服务器的稳定运行和高效性能。同时,服务器自带3M固定带宽,下载速度可达384KB/秒,且不限制流量,用户可以在使用过程中享受到稳定的网络连接速度。
|
消息中间件 安全 算法
G1和ZGC垃圾收集器
G1和ZGC垃圾收集器