Documentation 将自己与软件分离

我的工作包括技术分析。我喜欢软件开发，但那不是我的工作。然而，我已经开发了一个包含可执行文件、库、数据库和模块的实质性系统。说这样的产品让每个人的工作都变得容易并不是不现实的。我为每种产品都制作了大量的文档

在我的工作范围内，作为一个相当有能力的软件开发人员实际上是有害的（如果你原来的工作不是软件开发），这意味着你可能很快就被降级到软件维护，更糟糕的是，你可能会被捆绑在一个项目上，因为“只有你知道软件”。如果你认为NASA的项目可以持续15-20年（旅行者已经持续了32年），那不一定是件好事。即使你和其他人一样优秀，其他人也会转向令人敬畏的旗舰项目或核心工程（我的激情）

为了防止这种情况，我制定了以下规则：

如果你问一个问题，我会回答，但是 您可以在文档中记录答案 官方手册；如果您需要一个特性，我将与您一起在实际代码中实现它

我认为将会发生的是，用户在提问之前会更加努力（否则他们将不得不自己记录答案），随着新功能的添加，更多的人将了解软件的内部工作原理

足够的背景

具体来说，我想知道在您的软件开发生命周期中遵循了什么正式流程，以确保知识在整个组织中传播

我坚信这不是一个主观的问题，但会使社区维基避免冲突

---

谢谢。

确保文档涵盖出现的任何问题是一个好主意。出现这些问题是因为：

• 该功能还没有文档记录
• 文档是书面的，但不够清晰，或者假设读者还没有获得一些知识（需要交叉参考，或者只是围绕主题多做一点解释）
• 此人没有阅读文档（他们没有找到文档，甚至没有费心去寻找文档）

如果用户没有找到它，很可能是你帮了太多的忙，所以他们在查阅文档之前会先问你。你必须后退。否则，将有文档“bug”需要修复

然而，告诉用户他们必须记录事情的方法不太可能奏效。您将看到这种方法存在的问题有：

• 除非你有足够的影响力强迫他们，否则大多数用户根本不会这么做
• 大多数人的工作做得很差——满足要求的最低要求
• 即使他们付出了一些努力来做好“好”的工作，文档仍然可能缺乏一致性——在提供的信息量、使用的语言、文档的目标级别以及将对读者已经知道的内容进行的假设方面

最终，您可能需要充当一名编辑，或者自己编写文档

你规则的另一部分更好。不要只是为人们做事，要回击他们，给他们足够的信息，让他们能够帮助自己。正如您所说，这有助于传播知识，也有助于其他人帮助您扩展系统。这枚硬币的消极一面可能是，其他人也可能侵入，随着时间的推移，你会发现你整洁/有组织/稳定的结构开始变得更加凌乱和凌乱

最终，可以更好地为您服务的方法有：

• 与你的经理交谈，并要求你有机会继续进行更令人兴奋的项目，也许一周的一部分时间分配给维护/保管职责。一个欣赏你技能的好经理会尽力帮助你获得工作满意度和职业发展
• 担任一名替补——一名初级程序员，他被邀请来帮助您维护系统，直到他有足够的知识来接管维护者的角色。同样，这也是你的经理要做的事情，作为一种解放自己、迎接新挑战的方式。提醒你的经理，在新项目中，你的技能对公司更有用
• 如果你的经理不帮你前进，我发现真正摆脱遗留软件纠缠的唯一方法就是等待软件停止使用（这可能需要很长时间），或者转移到一家新公司（这会产生立竿见影的效果，但可能会让你从零开始为一家新公司重建一个类似的系统）

---

这是一个非常重要的问题——一个必须尽早思考的问题。为一个人离开项目、生病或（上帝禁止）被卡车辗过的情况做好准备是一件重要的事情，我相信，出于保护工作的错误意识而不这样做，最终会让所有相关人员落泪。我喜欢这个规则，在移交项目时，我曾尝试设置类似的工作流。