写点什么

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

  • 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:001808
用户头像
刘燕 InfoQ高级技术编辑

发布了 918 篇内容, 共 322.6 次阅读, 收获喜欢 1697 次。

关注

评论 2 条评论

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

阿里P10带你深度剖析:淘宝网是如何基于Spring Cloud微服务框架搭建大型电商平台设计

Java架构追梦

Java 架构 面试 微服务 SpringCloud

企业级软件的核心价值

Marilyn

敏捷开发

技术分析:AnalyticDB强力支撑双11

阿里云情报局

数据库 互联网 数据分析 双十一 数据舱

区块链钱包APP开发,开发搭建数字货币钱包

13530558032

作业--week08

张荣召

简要分析近几年商业软件开发平台的现状

Learun

企业 企业开发 企业应用

缓存与数据库一致性策略

洛神の殇

区块链赋能供应链金融 | 应用优势与四类常见模式

CECBC

区块链 供应商审核

8.3红黑树原理与性能特性

张荣召

8.5网络通信基本原理与性能优化

张荣召

简要分析近几年商业软件开发平台的现状

Marilyn

快速开发 企业开发

企业级软件的核心价值

Learun

敏捷开发 快速开发 企业开发 企业应用

函数式编程:如何高效简洁地对数据查询与变换

华为云开发者联盟

编程 面向对象 数据处理

区块链带来的业务流程优化是数字化转型最深层次的变革

CECBC

区块链 数字化

8.2常见数据结构与Hash表原理分析

张荣召

Week 8 命题作业

阿泰

架构师训练营 1 期 - 第八周作业(vaik)

行之

数字货币合约交易所系统开发技术

薇電13242772558

区块链 数字货币

用废旧纸箱DIY智能宠物喂食器!旅行在外远程投喂“二狗子”

智能物联实验室

物联网 DIY 智能硬件

微服务下,使用 ELK 进行日志采集以及统一处理

华为云开发者联盟

微服务 Kibana ELK

云图说|云上攻击早知道,少不了这个“秘密武器”!

华为云开发者联盟

安全 云服务 云端

建行数字债券允许比特币交易?官方回应了!业内人士:交易架构的创新值得赞赏

CECBC

比特币 债券

重磅发布!Flink Forward Asia 2020 在线峰会预约开启!

Apache Flink

flink

数字货币交易所开发定制,币币撮合交易开发商

13530558032

8.4经典算法

张荣召

8.6非阻塞网络I/O

张荣召

Mock服务设计与实现:MySQL驱动字节码修改增强

华为云开发者联盟

MySQL 数据库 sql

飞书的「背道而驰」

ToB行业头条

自己写歌怎么编曲?4款超好用编曲软件推荐

奈奈的杂社

编曲 音频制作 midi daw

区块链USDT系统开发解决方案,USDT支付系统技术开发

13530558032

8.1文件与磁盘IO:如何把磁盘的读写速度提升十万倍?

张荣召

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