写点什么

软件的下一个飞跃:修复内部文档

2020 年 12 月 19 日

软件的下一个飞跃:修复内部文档

你以前听过这个故事吗?一位经验丰富、备受重视的软件工程师加入了一家新公司。她急切地提供价值。她的团队渴求提高生产力,因为每个人都忙得不可开交。然而,她所发现的是一个庞大的、文档化程度低的、令人费解的代码库。


花了好几个月的时间,她才搞清楚所有的东西在哪里,什么东西在哪里。同时,团队的生产力也在下降,因为他们需要指导她完成部分代码,而这些代码有时连他们自己都不太记得。


预计到 2024 年,全球软件工程师的数量将达到近 2900 万,每年引进大约 100 万名新开发者。与此同时,科技行业的营业额也在不断增长,与其他行业相比,目前是最高的


由于每年有 300 万到 400 万的工程师在更换公司,还有数百万的工程师在不同的团队或项目之间转换,所以使用新的代码库已经成为软件开发的最大挑战之一。


软件工程师是所有软件公司和研发部门中最受欢迎和最有价值的资源。在未来十年内,提高软件工程师的工作效率预计可使全球 GDP 增加 3 万亿美元,96% 的 C 级主管表示,提高开发者的工作效率是他们组织中的中高优先事项。


由于新冠肺炎疫情爆发,提高生产力和效率的需求变得更为迫切,许多新开发者都是从远程办公开始,不能获得同等水平的办公室内培训和经验。


对于工程师来说,很少有事情像新代码库的入门流程那样阻碍他们的工作效率。近几年来,我和几十家公司的经理们就工程师上岗问题进行了讨论。


在这些公司中,工程师们完全掌握技术所需的时间通常需要三到九个月的时间。有些情况下,他们会花上一整年的时间。这种情况对于与快速发展的公司或人员流动频繁的工资尤其有害,因为他们的工程师中有很大一部分并没有完全发挥出生产力,而其余的工程师们则忙于帮助他们。


内部文档化很难进行


对于外部观察者来说,解决方案似乎很简单:在创建和更改代码时,推广文档化的文化,这样,新员工入职过程就会变得更加精简和优雅。在全球范围内这样做,你将会获得更高的工作效率。


然而,几十年的代码项目已经表明,创建和维护内部文档由于各种原因是一个巨大的挑战:


  • 这是一项耗时的投资。

  • 要保持新鲜和相关性,就需要更多投资。

  • 创建代码远比记录文档更令人兴奋,更有成就感。

  • 并不是每一个开发者都是文档化的拥护者,这导致了文档的编写得很糟糕,与代码和工作流的链接也很槽糕。

  • 由于开发者偏好不同的平台,所以文档往往分散在不同的平台上,而不利于集成和使用。

  • 在文档化方面的投资主要是一种利他主义行为,需要团结和同理心,而这种团结和同理心很少是自然发生的。这就需要管理层的重视和资源分配。


这种动态性使得许多人认为,有文档和没有文档一样有用。有些人提倡“自文档化代码”,要求代码清晰、组织有序,不需要其他文档。然而,事实证明,这种方法同样难以培养和维持,因为它也需要利他主义、努力、时间和技能。


颠覆时机已成熟


随着开发者工具市场的稳步增长和资本的涌入,似乎新一代文档工具的基础已经准备就绪。然而,要想产生重大影响,新工具需要解决以下几个重要问题:


  • 维护自动化:文档化问题的症结在于需要花费时间和精力来更新文件。新的工具必须在不降低质量的情况下解决这一问题。

  • 工作流程的一部分:如果文档化仍然是你在不进行编码的时候所做的事情,那么就永远不会有足够的时间去做好它。在开发过程中使用文档工具,并将其纳入开发过程,以最小的努力实现它。

  • 与代码相结合:当文档脱离代码本身时,它往往会脱离实际而失去意义。只有代码才是真理的源泉:只是很少有足够的清晰和组织。文档应该解释原因、上下文和流程,但要将它们与代码中的相关部分直接联系起来。

  • 开发者的喜爱:如果这些工具要得到开发者的认可,就必须得到他们的喜爱。事实证明,“开发者体验”是开发工具的决定性因素,在这种情况下也不会例外。


新冠肺炎疫情爆发产生了破坏性的影响,但也加速了新技术的开发和采用。事实证明,远程办公是一个艰巨的挑战,而新的工具在今天的环境中提供了肥沃的土壤和机会,从而永远地改变了代码文档的创建和维护方式。


作者介绍:


Tom Ahi Dror,Swimm 首席品牌官,致力于改变开发者进入新代码库的方式。


原文链接:


https://www.forbes.com/sites/forbestechcouncil/2020/12/09/softwares-next-big-leap-fixing-internal-documentation/?sh=7799f69613bb


2020 年 12 月 19 日 08:001564
用户头像
刘燕 InfoQ记者

发布了 507 篇内容, 共 157.2 次阅读, 收获喜欢 944 次。

关注

评论 2 条评论

发布
用户头像
很多小公司都不重视文档,乱七八糟的,新员工来了都不能立即上手。
2020 年 12 月 19 日 11:10
回复
文档本身具有时效性,不是人的问题而是思考问题的方式应该改变,整个行业都这样,就不是人的问题,而是维护文档这件事,甚至是方法本身思考问题做事的方式有问题
2020 年 12 月 22 日 21:00
回复
没有更多了
发现更多内容

架构训练营第五周作业

Geek_ce484f

极客大学架构师训练营

架构师训练营第 1 期 -Week5 - 技术选型一学习总结

鲁小鲁

极客大学架构师训练营 负载均衡架构 缓存架构 消息队列架构

Netty源码解析 -- ChannelOutboundBuffer实现与Flush过程

binecy

源码分析 Netty nio

第一周学习总结

晴空万里

极客大学架构师训练营

食堂就餐系统

落朽

week05学习总结

追风

架构师一期

【第五周】课后作业

云龙

架构师训练营第五周课程笔记及心得

Airs

week05作业

追风

架构师一期

架构师训练营 第一周 作业 食堂就餐卡系统设计

阿光

UML作图

Arthur

极客大学架构师训练营

[架构师训练营第 1 期] 第五周命题作业

猫切切切切切

极客大学架构师训练营

一致性Hash算法的实现及分析

天天向上

极客大学架构师训练营

架构师训练营第1期第五周作业

Leo乐

极客大学架构师训练营

架构师训练营 1 期 -- 第五周笔记

曾彪彪

极客大学架构师训练营

架构训练营第五周作业总结

Geek_ce484f

极客大学架构师训练营

架构师训练营第二期Week 1作业

bigxiang

极客大学架构师训练营

极客时间第 2 期架构师训练营第一周作业 1

willson

架构师训练营第二期 Week 1 总结

bigxiang

如何将文章高效发布到多个平台|MWeb 七牛云图床配置

彭宏豪95

写作 markdown 图床 MWeb

架构师训练营第 5 周学习总结

netspecial

极客大学架构师训练营

架构师训练营 Week5 技术选型 - 缓存/消息队列/负载均衡

负载均衡 缓存 消息中间件

架构师训练营 1 期第 4 周:系统架构 - 总结

灵霄

极客大学架构师训练营

第一章学习笔记

博博

架构师训练 第一周 学习总结

阿光

架构师训练营 - 作业 - 第五周

Max2@12

食堂就餐卡系统设计

水浴清风

架构设计学习笔记1

Arthur

极客大学架构师训练营

[架构师训练营第 1 期] 第五周学习总结

猫切切切切切

极客大学架构师训练营

架构设计-UML案例

食堂就餐卡设计

博博

微服务架构下如何保证事务的一致性

微服务架构下如何保证事务的一致性

软件的下一个飞跃:修复内部文档-InfoQ