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

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

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

预计到 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