04 | 如何降低认知负载：活的文档能救命
姚琪琳
你好，我是姚琪琳。
在第三节课，我带你了解了认知心理学中的一个概念——认知负载。这个看似与软件开发毫无瓜葛的知识，实际上却决定了软件系统的成败。因此在遗留系统现代化中，我们把“以降低认知负载为前提”作为首要原则。
有些同学这时就会问了，你总说认知负载如何如何，降低认知负载又是多么重要，那怎么才能真正降低认知负载呢？别着急，我们今天就来看看有哪些方法能降低认知负载。其中最重要的工具，就是活文档。
什么是活文档
活文档（living document），顾名思义，就是指活着的文档，也就是在持续编辑和更新的文档，有时候也叫长青文档或动态文档。比如维基百科中的一个词条，随时都有人更新和维护，这就是一个活文档。与之相对的是静态文档，也就是一旦产生就不会更新的文档，比如大英百科全书中的一个条目。
你可以想象一下，在软件开发过程中，无论是瀑布模式还是敏捷，我们拿到的需求文档或故事卡是“维基百科”还是“大英百科”呢？我想大多数情况可能是，在最终需求还没有敲定时还是“维基百科”，也就是还会随时更新，而一旦敲定开始开发后，就变成了“大英百科”，再也不会更新了吧。
然而随着需求的不断叠加，“大英百科”作为当时系统的一个“快照”，早就已经失去了时效性。只有将不同时段、不同模块的文档片段合并在一起，才能得到当前系统的快照。但这个合并放在现实中是很难操作的。
公开
同步至部落
取消
完成
0/2000
荧光笔
直线
曲线笔记
复制
AI
- 深入了解
- 翻译
- 解释
- 总结
活文档：降低认知负载的利器 活文档是降低认知负载的重要工具，通过在代码中添加注解，并利用工具生成脑图，可以将复杂的业务代码转化为易于理解和记忆的结构，从而降低认知负载。实例化需求的方式编写的测试也是一种活文档，能展示业务知识，随代码更新，提高系统的可维护性和可扩展性。依赖分析工具可以展示系统知识，帮助理清系统内的依赖关系。活文档为软件开发带来了新的思路和方法，对于降低认知负载、提高系统的可维护性和可扩展性具有重要意义。
仅可试看部分内容，如需阅读全部内容，请付费购买文章所属专栏
《遗留系统现代化实战》，新⼈⾸单¥59
《遗留系统现代化实战》，新⼈⾸单¥59
立即购买
© 版权归极客邦科技所有，未经许可不得传播售卖。 页面已增加防盗追踪，如有侵权极客邦将依法追究其法律责任。
登录 后留言
全部留言(9)
- 最新
- 精选
Kent活文档是个好东西 - 产品文档、技术文档常常是项目在某一个时刻的快照，不一定准确 - 代码里留下归纳性的注释表明代码意图(函数、控制流) - 修改功能、重构结构时，也应当及时更新对应的注释文档 - 单元测试代码也能表明代码的用途和边界 - 代码和文档(注释)放在一起，比分开在wiki中要轻松方便 - 用好代码分析工具能事倍功半（虽然往往没有这种现成的工具[doge]）作者回复: 感谢分享
2022-05-083
killerDDL（Data Definition Language）迁移到代码库中，进行版本化，楼主你们用的什么工具？作者回复: Flyway
2022-04-211- Jack_1024有木有开源的轮子呀
作者回复: 目前还没有哦，可以自己开发一个
2022-04-23 
西米活文档工具 通过注解扫描，.NET 有类似的工具吗？作者回复: 应该没有线程的，Java的工具其实就是扫描字节码，.NET就扫描IL就可以了，自己可以开发一个
2022-04-21- killer工具分为两种一种是动态的，一种是静态的 1、动态的可以利用SKyWalking 全链路追踪等 2、静态的需要在api，mq，enum加上注解，依赖编译预处理javax.annotation.processing， 提取项目的源信息
作者回复: 感谢分享👍
2022-04-212 
aoe之前只知道测试可以作为文档，今天看了老师生成的知识图谱，感觉效果更好。 关于发布/订阅模式（尤其是发出一个消息，多个消费者订阅的场景）有如下问题： 1、有没有适合这个场景的插件？ 2、SkyWalking 可以看到完整的调用链路（本地方法调用、RPC调用、Redis、MySQL、消息中间件），但是调用链路总体太长（一个Http请求几百个），虽然有图展示出来，但看到后依然惊人崩溃！（我觉得这样的代码还是优先调整代码结构，使其向单一原则、不要和陌生人说话方向发展比较好） 补充：很多链路追踪工具也可以查看调用链路（例如:ZipKin）作者回复: 确实对于调用链复杂的遗留系统来说，用工具可视化出来的图表也是相当吓人的，并不能显著降低认知负载，还是要先进行一些局部优化。
2022-04-18
静✨唉…不管是代码还是数据库 老师都做了我想做的事情(感叹自己技术不足 伟大！期待开源的那天到来2022-07-172
_立斌老师你好，针对遗留系统动辄三五千行的方法，估计得重构过后才能变成注解活文档了？因为大量逻辑都写在同一个方法里，并且大部分逻辑并没有抽取方法出来，这种老大难方法应该如何构建活文档呢2023-10-07归属地：广东
子夜枯灯期待有开源的工具分享2022-04-26
收起评论
