documentation - 将自己与软件分开

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改进这个问题？更新问题，以便 editing this post 可以用事实和引用来回答它.

4年前关闭。




Improve this question




我的工作包括技术分析。我喜欢软件开发，但这不是我的工作。然而，我已经开发了一个由可执行文件、库、数据库和模块组成的庞大系统。说这样的产品让每个人的工作变得更轻松，这并不是不切实际的。我为每个产品制作了大量的文档。

在我的工作中，成为一个相当称职的软件开发人员实际上会受到伤害(如果你最初的工作不是软件开发)，这意味着你很快就会被降级为软件维护，更糟糕的是，你可能会被束缚在一个项目中，因为“只有你知道这个软件”。如果你认为在 NASA 一个项目可以持续 15-20 年(Voyager 已经持续了 32 年)，那未必是好事。即使你和任何人一样优秀，其他人也会继续进行出色的旗舰项目或核心工程(我的热情)。

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

If you ask a question, I respond but you document the answer in the official manual; if you ask for a feature, I will work with you implementing it in the actual code.

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

足够的上下文。

具体来说，我想知道在您的软件开发生命周期中遵循哪些官方流程，以确保知识在整个组织中传播。

我坚信这不是一个主观问题，但会使其成为社区 wiki 以避免对抗。

谢谢你。

Answer 1

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

该功能尚未记录

文档已经写好，但不够清晰，或者假设读者还没有获得一些知识(需要交叉引用或围绕主题进行更多解释)

此人没有阅读文档(他们没有找到它，甚至没有费心去寻找它)

如果用户没有找到它，很可能是你太有帮助了，所以他们在查阅文档之前会问你。你必须推回去。否则，有文档“错误”需要修复。

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

大多数用户根本不会这样做，除非你有足够的影响力来强制他们

大多数人会做得很差-满足要求的最低限度

即使他们付出了一些努力来完成“好”的工作，但文档可能仍然缺乏一致性——在提供的信息量、使用的语言、文档的目标级别以及将对读者已经知道的内容做出假设。

最终，您可能必须充当编辑，或自己编写文档。

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

最终，可能更好地为您服务的方法是:

与您的经理交谈并请求您有机会继续进行更令人兴奋的项目，也许您一周的一部分时间分配给维护/保管职责。欣赏您技能的优秀经理会尽力帮助您获得工作满意度和职业发展。

找一个替补——一个初级程序员，他被请来帮助你维护系统，直到他有足够的知识来担任维护者的角色。再一次，这是你的经理需要考虑的事情，作为一种让自己腾出时间迎接新挑战的方式。提醒您的经理，您的技能在新项目中对公司更有用。

如果你的经理不帮助你前进，我发现真正摆脱遗留软件纠缠的唯一方法是等待软件停止使用(可能需要很长时间)，或者移动到一家新公司(这会立竿见影，但可能会让您为新公司从头开始重建类似的系统)。