QCon广州站Web 3.0 专题上线,关注基础设施及相关技术,戳此了解 了解详情
写点什么

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

  • 2020 年 12 月 19 日
  • 本文字数:1705 字

    阅读完需:约 6 分钟

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

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


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


预计到 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:001771
用户头像
刘燕 InfoQ记者

发布了 855 篇内容, 共 289.3 次阅读, 收获喜欢 1620 次。

关注

评论 2 条评论

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

一个草根的日常杂碎(10月5日)

刘新吾

随笔杂谈 生活记录 社会百态

4 个问题图解浏览器垃圾回收的过程

Java架构师迁哥

区块链带来第四次技术革命 融入生产大幅提高企业收入

CECBC

区块链 数字资产 技术革命

金秋十月重磅技术文——网络编程大揭秘

Java架构师迁哥

编程 程序员

makefile从入门到入门

MySQL从删库到跑路

c++ Linux 编译 makefile

《统计学习基础:数据挖掘、推理和预测》-斯坦福大学人工智能学科专用教材

计算机与AI

架构师训练营第三周心得

CmHuang

【知识分享】区块链常用术语

CECBC

区块链 货币 网络节点

阿里P8大牛爆肝的《Java核心技术总结》+《面试题总结》简直赞爆了

Java架构之路

Java 程序员 面试 编程语言 进阶

云服务器网站打开速度过慢,如何进行自检

德胜网络-阳

手把手教你AspNetCore WebApi:增删改查

AI代笔

ASP.NET Core web api EF Core

看了这篇网络编程,就可以和面试官聊聊了

Simon郎

网络编程 websocket Java 分布式

Linux搭建C++开发调试环境

MySQL从删库到跑路

c++ Linux gdb 编译

spring-boot-route(六)整合JApiDocs生成接口文档

Java旅途

Java Spring Boot

作者谈《阿里巴巴Java开发手册(规约)》背后的故事

Java架构师迁哥

spring-boot-route(七)整合jdbcTemplate操作数据库

Java旅途

Java Spring Boot JDBC

区块链--凌驾于政治之上的存在

CECBC

区块链 信息技术

Chrome浏览器架构

曲迪

chrome 大前端 浏览器 专栏

Code Review怎么做

胖鱼2号

小伙伴想学Jenkins自动构建发布项目,我:安排上了!!

冰河

项目管理 jenkins 灰度发布 自动构建 及时发布

架构师训练营 Week4 系统架构 - 学习总结 架构演进

架构师训练营第 1 期 - 第 4 周 - 学习总结

wgl

我把这个贼好用的Excel导出工具开源了!!

冰河

Java Excel 冰河 mykit-excel

架构师训练营第四周作业

邓昀垚

极客大学架构师训练营

LeetCode题解:102. 二叉树的层序遍历,递归,JavaScript,详细注释

Lee Chen

大前端 LeetCode

手把手教你锤面试官01——HashMap面试全攻略

慵懒的土拨鼠

面试 java基础

叹为观止!GitHub标星过万,腾讯技术官发布的“神仙文档”图解网络,简直是秋招福音

程序员 互联网 网络通信协议 计算机知识

纸质书和书写的慢时代

boshi

随笔杂谈

手把手教你AspNetCore WebApi:入门

AI代笔

ASP.NET Core web api

手把手教你AspNetCore WebApi:Swagger(Api文档)

AI代笔

ASP.NET Core swagger web api

中台: 54 天搞定中国百强企业的库存中心建设,而时间还能够再缩短至少一倍

日编一码

软件的下一个飞跃:修复内部文档_AI_Tom Ahi Dror_InfoQ精选文章