地图、黄金和香料：为何忽视记录可能会毁掉你的项目

古代探险家从航海中带回的最宝贵的财富是什么？黄金和香料？错了。是地图。

如果没有地图他的前辈设计了这一计划。一场获取葡萄牙地图的间谍游戏为荷兰东印度公司奠定了基础，该公司可以说是人类历史上最昂贵的公司。在 1637 年的巅峰时期，它的价值为 7800 万荷兰盾，相当于7.9万亿美元按 2017 年美元计算，这一数字将超过 10 万亿美元，超过微软、Nvidia 和苹果合并从短期来看，来自新大陆的触手可及的宝藏固然重要，但从长远来看，知识才是创造真正财富的手段。

为什么在当今的科技世界里我们往往会忘记这一点？为了追求即时的成功，我们往往不愿意投入宝贵的时间和资源来制作和维护技术文档。用 17 世纪的话来说，我们急于抢夺黄金和香料，却没有绘制地图，而这反过来又可以让我们获得更多的黄金和香料。你怀疑吗？喂，让我们仔细看看……

古怪的代码

“您肯定记得，大脑神经元模式的催眠停滞状态可以通过超电磁束扫描——” “别这样！”阿德·瓦克不耐烦地说。“您说的是什么意思——我们肯定记得？”我们怎么能记得我们不知道的事情呢？ ——这句话出自伟大的科幻作家埃德蒙·汉密尔顿的小说《古怪的世界》，指的是火星人，而不是程序员。然而，许多人认为开发人员来自另一个星球——尤其是那些对软件开发及其复杂性只有模糊概念的人。事实上，开发人员经常认为其他人和他们一样了解代码，并且经常认为技术文档是不必要的。这种心态可能会让项目变得像“催眠停滞状态”一样复杂，让局外人难以理解，最终危及项目的潜在成功。

不愿创建文档的原因通常与人们在其他领域拖延的原因相同：它需要大量的时间和资金投入。换句话说，这通常是由于纯粹的懒惰和想要省钱，而这些都不是容易克服的障碍。然而，文档不仅仅是每个人都显而易见的冗余信息；它还包含不可或缺的关键细节。通常，缺乏文档会使错误的检测和纠正变得非常复杂，使维护和更新更加困难，并增加新团队成员入职所需的时间。没有文档的团队只能做重复性的任务，而拥有结构良好的文档的项目则表现出很高的效率和可靠性——这是事实，而不仅仅是一种观点。

是的，有些程序员声称他们编写的代码非常清晰易懂，文档根本不必要。然而，事实上，即使是最完美的代码也会让其他人感到困惑，或者随着时间的推移变得不再清晰。今天看似清晰的东西明天可能会变成一个谜。例如，你能轻松处理 70 年代的简单打孔卡吗？

《巴士因素》、《火爆狂飙》和其他神奇动物

理论固然好，但实践更有说服力。以下是一些基于真实故事的例子，其中只有人物和公司的名称是虚构的。这些简短的案例研究涵盖了由于技术文档编写不当而产生的最典型问题。

故事一：无法扩展

“NoDocumentationPlease”项目最初是一家成功的视频流媒体初创公司，但由于技术文档不佳，在尝试扩展时遇到了严重问题。当团队需要扩展时，新员工无法完全理解他们的任务，没有人能为他们提供充分的解释。如果没有适当的支持和培训，新员工很快就会离开。这不仅减缓了项目的进展，还导致关键人才的流失，最终危及项目的整体效率和未来。结果，主播们离开了聊天室，项目被关闭了。

故事2：维护问题

“IKnowEverything” 公司开发了一个用于数据同步和存储的云平台。最初，该项目进展迅速，但随着时间的推移，由于缺乏清晰且最新的技术文档，开发人员在维护和更新平台方面面临困难。这导致开发速度变慢、错误增多，客户不满意。最终，该公司开始失去老客户，新客户选择提供更稳定、更可靠的解决方案的竞争对手。收入大幅下降，而无效维护的成本却增加了。从一开始就正确记录技术方面可以让他们成功扩展。然而，这项工作没有及时完成。因此，该公司无法克服技术和财务挑战，最终倒闭了。

故事 3：开发人员倦怠

“SmartestEver”项目面临严重问题，因为负责处理所有事务的主要开发人员 Andrew 被团队的大量问题压得透不过气来，于是辞职了。如果“SmartestEver”有适当的文档，初级开发人员就可以轻松地参考常见问题解答并解决常规问题。然而，他们却向 Andrew 提出大量问题，没有他和必要的文档，团队就无法继续下去，项目也关闭了（按 F 键代表 Andrew）。

故事#4：巴士因素

在“NoDocsNeeded”公司，一款很有前途的软件产品由一位关键开发人员 John 开发，他掌握了所有的知识，但却懒得去记录。他的经理们也懒得去说服他。有一天，John 出差了，就再也没有回来。没有文档或对产品架构和逻辑的理解，剩下的团队成员基本上什么也做不了。项目被冻结，投资的资金也打了水漂。教训很简单：团队内部的文档和知识分配对于避免对一个人的依赖至关重要。顺便说一句，他们还在找 John……

故事#5：开源不欢迎先知

Maria 创建了她的第一个开源库，但没有为其编写任何文档。没有人理解这个库的作用，Maria 决定不再编写任何库，因为对她来说这似乎毫无意义。Maria 的项目甚至还没开始就结束了，她决定换个职业。

从船上服务员到船长

好的，我们了解了一些理论和实践，现在让我们深入研究和统计。 Stack Overflow 开发人员调查 2024州84% 的受访者使用技术文档来了解技术的功能。然而，即使有文档，他们也常常找不到所需的答案，接下来最受欢迎的资源如下：Stack Overflow（80%）、书面教程（68%）、博客（61%）和操作方法视频（54%）。微软研究：软件开发人员的日常生活 成立平均而言，开发人员每天会花 1-2% 的时间（8-10 分钟）在文档上，10.3% 的开发人员表示过时的文档迫使他们花费太多时间自行寻找答案。文档的必要性也是学术界关注的一大问题。在 Google Scholar 上简单搜索 <“documentation” AND “software”> 产量超过 400 万个结果，清楚地表明有大量的科学出版物讨论这一问题。

主要结论非常简单：#1 – 每个人都需要文档来理解技术和/或其他人的工作；但#2 – 很少有人费心编写和维护文档；因此#3 – 很多文档写得不好、过时且通常毫无用处。那么该怎么做呢？从各个层面改变你的动机。

来自荷兰汉诺威应用科技大学和格罗宁根大学的一组研究人员已识别技术文档最典型的问题：

• 开发人员经常使用的非正式文档很难理解；

• 如果文档不能立即对最终产品做出贡献，则被视为浪费；

• 开发人员的生产力仅以可运行的软件的数量来衡量；

• 文档通常与实际软件不同步；

• 开发人员通常只关注短期目标，尤其是在持续软件开发环境中。

  
  

这些听起来熟悉吗？我敢打赌，我们大多数人在日常工作中都曾遇到过大多数甚至所有问题。而这不仅仅是拖延或缺乏资源。其中一些问题来自缺乏适当的管理、长期规划，以及最终的战略眼光。而困难的部分就在这里，因为这不仅仅是我们开发人员要解决的问题。有些问题应该由经理、产品利益相关者甚至公司所有者来处理。这就是为什么正确的技术观点至关重要，它不仅仅是一个漂亮的附属品，而是整个公司的核心价值观的一部分，从创始人到初级开发人员，每个人都应该认同。