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

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

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


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

 

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

 

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

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


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

 

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

 

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

 

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


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


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

 

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


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

 

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

 

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

 

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

 

 

 

 

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

目录
相关文章
|
7月前
|
C语言 C++ 开发者
深入探索C++:特性、代码实践及流程图解析
深入探索C++:特性、代码实践及流程图解析
|
7月前
【sgTopo】强哥古法炮制、纯手工打造简单拓扑图、流程图、思维导图组件(完善中ing)(二)
【sgTopo】强哥古法炮制、纯手工打造简单拓扑图、流程图、思维导图组件(完善中ing)
|
7月前
|
网络协议 Java
【工具】Mermaid + 大模型画流程图
最近看面试文章关于TCP三次握手和四次挥手的文章,时常会看到有类似的图去描述这样的过程。当然觉得这样的图还是蛮规范的,属于流程图的一种,是否有工具可以自动生成呢?但没有细想,昨天刷V2EX看到也有老哥发出了这样的问题。于是顺着评论区大佬的回答,我GET到了一个工具Mermaid 这里三次握手的图取自小林coding的文章
436 0
|
7月前
|
API 开发工具 数据库
OneCode2.0源码结构分析
OneCode12月10日正式更新了其V2.0版本。从OneCode的季度版本生命中,可以看到2.0版本还是一个重量级的版本,笔者在收到2.0更新后第一时间下拉了最新的代码。在参考了OneCode 的技术说明后,根据包结构来分析一下OneCode2.0的结构。
|
存储 人工智能 算法
详细设计工具之盒图(N-S图)
详细设计工具之盒图(N-S图)
1224 0
详细设计工具之盒图(N-S图)
|
5月前
画好一张架构图/业务图/流程图问题之如何让图结构更清晰问题如何解决
画好一张架构图/业务图/流程图问题之如何让图结构更清晰问题如何解决
|
7月前
|
传感器 运维
【软件设计师备考 专题 】编写外部设计文档:系统配置图和关系图
【软件设计师备考 专题 】编写外部设计文档:系统配置图和关系图
112 1
|
7月前
【sgTopo】强哥古法炮制、纯手工打造简单拓扑图、流程图、思维导图组件(完善中ing)(一)
【sgTopo】强哥古法炮制、纯手工打造简单拓扑图、流程图、思维导图组件(完善中ing)
|
JavaScript 前端开发 API
使用Jsmind实现前端流程图功能
使用Jsmind实现前端流程图功能
|
uml C++
VS工具使用——代码生成函数关系图
小引: 在上篇文章《VS工具使用——代码图》中,我向大家介绍了我对工具“代码图”的发现和认识。真是感觉当自己的眼睛不再被蒙蔽的时候,会发现整个世界的美好。所以,这次要向大家介绍我对VS中的另一个容易被忽视的工具—— 自动生成代码关系依赖图的理解。
594 0