写点什么

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

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:001617
用户头像
刘燕 InfoQ记者

发布了 598 篇内容, 共 189.6 次阅读, 收获喜欢 1158 次。

关注

评论 2 条评论

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

python 爬虫之selenium可视化爬虫

诡途

Python 爬虫 selenium

寻找被遗忘的勇气(二十二)

Changing Lin

3月日更

大前端工程师进阶之路,Node全栈为前端带来更多可能

孙叫兽

前端 全栈 Node

助力香港成为全球寿命最长的城市,我们如何看医管局的数字化转型?

有只小耳朵

数字化转型 人才培养

爬虫入门经典(十八) | 滑动验证码识别

不温卜火

python 爬虫

实时 摔倒识别 /运动分析/打架等异常行为识别/控制手势识别等所有行为识别全家桶 原理 + 代码 + 数据+ 模型 开源!

cv君

人工智能 目标检测 视频理解 图像分类

C 语言性能优化:循环展开

一笑置之

编程 程序员 性能优化 C语言 循环展开

手把手教学基于深度学习的遥感影像倾斜框算法训练与分析

cv君

人工智能 深度学习 AI 智能 视觉

初来乍到,请多关照

空城机

杂记

它终于来了!

Python测试开发

Python

飞桨中国行首站重庆 解读产业 智造

百度大脑

百度 飞桨 中关村智酷

爬虫入门经典(七) | 一文带你爬取淘宝电场

不温卜火

python 爬虫

爬虫入门经典(十五) | 邪恶想法之爬取百度妹子图

不温卜火

python 爬虫

前置机器学习(一):数学符号及希腊字母

caiyongji

机器学习

飞桨刷新分子性质预测榜单,助力AI药物研发

百度大脑

AI 药物研发 百度飞桨

Three.js杂记(三)—— 物体运动

空城机

JavaScript 前端 WebGL 3D可视化 three.js

【实战】基于TensorRT 加速YOLO系列以及其他加速算法实战与对比

cv君

人工智能 深度学习 学生党 目标检测 加速

想当程序员,如何判断自己是否适合当前端程序员?

孙叫兽

程序员 前端

波卡生态DeFi系统开发方案

薇電13242772558

区块链 defi

数据分析实战项目-蛋壳公寓投诉分析

诡途

Python 数据分析 蛋壳公寓

首席AI架构师进阶之旅开启!第4期60位AICA学员硬核开学

百度大脑

百度飞桨 AI架构师

【实战问题】-- 缓存穿透,缓存击穿和缓存雪崩的区别以及解决方案

秦怀杂货店

Java redis 缓存 架构 分布式

Three.Js杂记(一)——起步

空城机

前端 WebGL 3D可视化 three.js

如何巧妙的去除数组中的空格?

程序媛观澜

c++ 字符串

爬虫入门经典(四) | 如何爬取豆瓣电影Top250

不温卜火

python 爬虫

爬虫入门经典(十二) | 一文带你快速爬取豆瓣电影

不温卜火

python 爬虫

Git教程 - Git 命令与操作

信码由缰

git DevOps

2021年ONNX开发者大会即将召开

百度大脑

百度飞桨 ONNX

2.4 Go语言从入门到精通:条件和循环

xcbeyond

golang Go语言从入门到精通 3月日更

工作5年的阿里Java程序员,分享从业心得总结与面试笔记分享

周老师

Java 编程 程序员 架构 面试

Three.js杂记(二)——绘制点、线、面

空城机

JavaScript 前端 WebGL 3D可视化 three.js

Leader修炼指“北”:管理路上的大小Boss

Leader修炼指“北”:管理路上的大小Boss

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