设计文档中的流程图,靠得住吗?

简介: 本文讨论了软件开发设计文档中图形化设计图的重要性,如流程图、思维导图等,它们有助于清晰传达设计意图和提高沟通效率。然而,当面临迭代更新、人员变动时,基于截图的图形设计图可能会带来协作难题。作者提倡使用简单文字格式搭配标签和符号作为替代方案,分享了团队内部实践,通过表格来实现类似思维导图和流程图的功能,以增强文档的可维护性和协作性。同时,作者强调这不是反对使用设计图,而是提出在某些场景下的一种有效补充方法。

先别被标题误解。流程图、系统调用关系图、状态图、业务流程图、业务时序图,还有思维导图、架构部署图、用例图、类图,等等,这些是我们的软件开发设计文档的不可或缺的组成部分。这些设计图能够以直观、清晰的方式传达设计意图,使得开发人员、测试人员和利益相关者更容易理解和沟通系统的设计和实现。一个只有文字排版而缺乏设计图的文档可能会显得呆板和难以理解。文字可以提供详细的描述和解释,但对于复杂的系统设计和结构,图形化的设计图能够更直观地展示关键概念、关系和流程。


当前,支持绘制软件设计图的工具不胜枚举,无论是MS Office Visio、MindX软件,还是在线的processOn、小红书、mubu、百度脑图、etc.。

 

我们在编写软件开发设计文档时,通常的做法是,将利用工具或软件绘制好的流程图,截图,然后贴到我们的文档中。互联网开发团队,通常是将设计文档放到内部WIKI上,实现资源共享。

 

不过,你是否遇到过这样的情况?系统需求有新的迭代开发时,业务流程发生变化,需要修改上一版的设计图。而当事开发者不再是上次迭代的开发者,这时,修改上一版设计图的话,如果是电脑软件还好,找前任索要,然后自己修改。而一旦是前任在线绘制的,那会麻烦一些,你可以去让前任登陆进去去完善原始文档,再截图发给你,放到这次需求迭代的设计文档中。虽然一些在线工具支持多人协作,但如果这样的情况经常发生,怕就是个现实的问题了。

再有,开发团队出现人员变更是不可避免的事情,某些同学可能会离开,新的同学又进来。这种情况下,在一个设计图的开发者离开团队后,这个设计稿件将无法完善,只能绘制新的文件版本。


再有,开发人员其实一个闷骚的裙体,大家日常开发配合过程中,沟通并不充分,这也是我们工作中出现的“信息不对称”的因素之一。要指出的是,我们多数开发人员是比较积极的,愿意主动去完善代码,完善文档。如果发现他人或曾经的设计文档中的疏漏,他们会鸟悄地改掉,这实在是优秀的品质。不过,对于图片形式的设计稿截图,就爱莫能助了。

 

我相信以上情况,在每个团队都有发生,每个开发者都有感触。

 

那么,有这些经历,我们就不绘制图形化的流程图了?非也,非也!存在即合理,我们亦不能一刀切。日常研发和团队管理过程中,我本人也经常会设计各种图表。这不仅能让团队里的伙伴直观的理解,我本人也是受益者——上传下达或与其他兄弟组沟通时,我无需拿着白板笔在会议室的白板上一遍一遍地重复书写潦草的字迹。

 

看到这里,大家可能迷糊了,你到底要说什么呢?嘿嘿,我其实是想分享我们的一个最佳实践。我有时更推荐用简单的文字格式,配以适当的标签、符号、html表格,来实现我的设计意图。下面我会列举一些例子。当然,有同学会反问,你这样做的话,岂不是人人皆可修改?是的,不用担心你的设计文档被破坏,开发组中的伙伴不会存在别样的居心。有必要再声明一下,分享这些实践,绝非主张摈弃设计图。对于复杂的业务逻辑,设计图无疑是不可替代的方案。企业应用系统通常具有复杂、多变、庞大的特征,研发团队在持续的需求迭代、系统升级过程中,编写可维护、易维护的文档,是需要引起关注、思考和探索的issue。就像我们编写可维护、易维护的代码一样。这是我所要表达的主旨。


下面的截图案例,均来自我们研发团队在公司内部WIKI上维护的开发设计文档。


🍀下面表格替代了思维导图,依然清晰、直观。

 

🍀下面table有效实现了一个跨职能流程图。


🍀下面table描述了一个简单的流程图。

 

🍀下面table详细说明了业务执行所产生的数据变化形态。

 

🍀下面文字通过tab和箭头,描述了一个功能的程序实现方案。

 

🍀下面时序图是用在线的腾讯文档excel表格设计的,你信吗?

 

 

 

 

🍀感谢阅读。不足之处,还望批评指正!

目录
相关文章
|
算法 测试技术
详细设计文档格式
1、背景 (背景、原因) 2、名词解释 (对文档中出现新的或不常见的名词、概念或简略语给出定义和解释) 3、设计目标 3.1、实现的功能 (概要描述要实现的功能,列出要实现的功能点及子功能点,并对每一个功能点进行详细说明。
5943 0
|
自然语言处理 并行计算 Linux
零成本带你体验手搓AIGC模型
零成本带你体验手搓AIGC模型
1277 0
零成本带你体验手搓AIGC模型
|
9月前
|
Cloud Native Serverless 数据中心
阿里云ACK One:注册集群支持ACS算力——云原生时代的计算新引擎
阿里云ACK One:注册集群支持ACS算力——云原生时代的计算新引擎
304 10
|
9月前
|
测试技术 API 数据安全/隐私保护
API 调试与管理工具选型思考:Apifox 和 Apipost,企业究竟该如何选择?
在企业级 API 调试与管理场景中,选择一款高效的工具至关重要。市面上的调试工具琳琅满目,而 Apifox 和 Apipost 是近几年两款备受开发者关注的 API 工具。二者都宣称为团队协作和接口调试赋能,但对企业来说,究竟谁才是更适合的选择呢?本文将从功能对比、用户体验、企业适配度和性价比等多个维度做一次全面解析,帮助你做出更明智的选择。
279 1
|
C语言
C语言基础语法
这段文字主要介绍了C语言中的基础语法,包括函数调用的不同方式(如使用位置参数或命名参数传递,处理变参数的情况)及如何正确地进行组合调用,并保持数据类型的统一。此外,还介绍了操作符的使用,如比较运算符和逻辑运算符(`and`、`or`、`not`)。相关详细内容和示例可以通过阿里云的帮助文档进一步了解,包括函数调用方式、评估表达式的设置方法、告警条件表达式的语法,以及查询语法结构等。这为初学者提供了理解和实践C语言编程的良好起点。
355 13
|
敏捷开发 前端开发 测试技术
软件开发工作流【详解】(含公司产品研发流程图、大厂研发架构图、大厂研发流程图)
软件开发工作流【详解】(含公司产品研发流程图、大厂研发架构图、大厂研发流程图)
7513 1
|
前端开发 JavaScript 开发者
雪碧图:图片合并的艺术!
雪碧图:图片合并的艺术!
|
存储 SQL 运维
Tablestore 与 Elasticsearch 在数据库查询加速场景使用对比
过去三十年,我们从企业应用开始,经历了 PC 互联网、移动互联网的爆发式发展,到如今的产业互联网。在这些不同时代,一直变化的是应用形态,不变的是核心数据的价值。对于核心数据的存储,首选的方案是使用数据库存储,从互联网初期开始,开源关系型数据库 MySQL 成长成为了数据库存储的第一选择,关系型数据库解决了数据的快速建模,高可靠存储和快速查询,但是关系数据库中的高效查询主要依赖二级索引,如果出现索引
2192 123
Tablestore 与 Elasticsearch 在数据库查询加速场景使用对比
|
存储 Kubernetes 负载均衡
【Kubernetes】神乎其技的K8s到底是什么,为什么被越来越多人使用
【Kubernetes】神乎其技的K8s到底是什么,为什么被越来越多人使用
36159 6
|
Java Maven
使用 maven 自动将源码打包并发布
使用 maven 自动将源码打包并发布
385 0