确定适当数量的文档

我目前工作的一般方法是-

尽可能避免记录

仅在有其他团队需要时记录

只是为了澄清，我不是指代码文档-我们这样做是指围绕设计过程的所有文档-如果是UML或DB Schema，类图和带有规范等的word文档。

我将列出老板未记录的原因：

1. 这很耗时-专注于实施
2. 如果设计更改-那么文档应该更改，麻烦倍增
3. 最后，您只得到数百页，没有人想要阅读，也没有人真正编辑，所以到了时间，它就会过时了
4. 这很痛苦-没有人真的想要这样做

现在我意识到我们的工作速度更快，但是我也记得花时间来到这里，直接跳到一些旧代码，什么都不懂。

实际上，我仍然没有得到大部分的旧代码，有时当我进入时，我会看到许多来自不同开发人员的补丁试图进行细微调整。

我确实认为，缺少文档会促进此类补丁，并且从广义上讲，缺乏对系统的理解。

我的问题是：

我们如何平衡文档，以便在团队之间增进持续的知识并且仍然快速有效？

我发现任何文档都比没有文档要好。适当的金额通常取决于我们必须要做的时间，或者取决于我们讨厌支持电话和电子邮件的时间。

您当前的团队成员似乎对他们的记忆有些不切实际的期望，或者他们对自己的写作技巧感到羞耻，并且不愿意练习。

我意识到我在这里是少数派（英语专业的研究生，攻读研究生院的软件工程专业），因为我没有家常文件。这是一个有价值的专业工具。我可能不会像一些同事那样觉得写作难，但这主要是因为我有更多的实践经验。我不认为除非有文档，否则项目不会完成，而且我通常是出于纯粹自私的原因而编写该项目：因此，我可以给人们一些东西而不是打电话和发电子邮件，或者我可以记住我们最近在谈论什么一个月左右，如果我需要在深夜支持的话，我可以参考一下我的工作方式。

处理文档的最佳方法是随便编写，就像编写测试代码一样。令人惊讶的是，一些预先编写的模板（带有标题，代码存根等）可以使文档更容易，更快捷地完成。这样，您可以随时捕获变化，并且随着时间的流逝，您没有太多的基础。这样您会更有效率，因为您可以根据需要引用文档，并在此过程中进行更改。例如，在Wiki中这样做可以使更新更容易，并且如果最新和最重要的内容始终在同一位置在线，则可以避免文档版本问题，并且可以将链接发送给需要阅读该文档的人。

如果您花一点时间进行文档记录，则所有工作都会更快，尤其是当新加入团队时，因为他们不必花所有时间来弄清楚所有事情。找出问题是我们工作中很有趣的一部分，但是当您必须急着修复生产时，这并不是一件有趣的事情。如果我们再写一些笔记，我们都会节省很多时间。

您的团队在测试或编写测试代码方面是否有相同的问题？如果没有，这将是一个更容易出售。

您的文档在许多方面很有用：
1）在您从事项目工作时，对您以及您的同事而言。

2）给你的顾客。拥有可以向用户显示的文档（包括图表）可以使会议中的讨论更加轻松，尤其是在讨论复杂的系统时。即使文档不完整，这也是一个起点。

3）致力继承您作品的人（三年之内甚至可能是您）。我的许多年轻同事认为他们会永远记住东西。我知道如果我不写下来的话，这周我将不会记得它。拥有文档可以使您不必花半天的时间来记住自己的结构，而不必再花全力。

4）对于您和其他人，如果情况出现政治或争议。作为在会议上做笔记的人，为了让自己保持清醒和抗烦，我经常是唯一拥有书面决定的人。写下来的人将赢得这场争端。下次有人说“记住我们去年冬天在会议室4开会时遇到的会议时，记得X吗？弗雷德在那儿，那位来自会计部门的人是谁？”

在我的最后几个雇主中，我们有一个“开发”维基。重要功能块（新的导入/导出提要，安全子系统的工作方式，系统在何处存储上传的文档等）都记录在该文档中。它通常是在代码审查步骤之前必须完成的项目。刚开始时通常会有一些抵制，但是一旦有人需要查找一些信息并且信息就在那里，您就会有另一个转换。

以Wiki格式保存它的好处是，您不太愿意进行所有漂亮的Word格式化等工作，而只写出需要保存的真实信息。大多数（如果不是全部）Wiki包将允许您上传文档或图像（如Visio UML图表或UI线框），因此您也可以拥有可视化的片段。

像大多数事情一样，我认为您应该努力做到尽可能少地工作。那是不一样的事情。

您无法逃避分配时间来编写适当的文档。但是，您要根据自己的工作量来平衡自己的情况，但是要留出15-20％的时间来记录所做的工作。团队中的每个人（包括您的经理）都必须参与其中，否则您将只是为了他人的利益而记录在案，并且一无所获。文档必须是开发过程中不可或缺的一部分。

文档应该告诉您为什么要做什么，而将HOW部分留给实际代码，而WHAT部分留给单元测试。还有什么是痛苦的。对于通常只需要起点的聪明人来说，这通常就足够了。

同样，不要忘记为代码库的每个大组件维护一个总体的高级架构。使招募新团队成员变得非常容易。

最后，每当添加一个古怪的修复程序时，都可以从注释链接到您的错误数据库-非常有用。

您的老板是对的，不要打印任何人都不会阅读的UML文档。我们团队中的工作是使用类图视图在模型中实时导航。原理是始终从代码中更新MOF和UML模型，并让类图仅是模型的查看者，而不能作为模型本身。

因为所有的复杂性都是在模型级别的后台完成的，所以它确实很好用。我可以在模型中重构项目，编写Java文档或编写uml文档。这是一种即点即用。单击后，您将获得实时文档。如果不清楚，请打开类图并开始使用它。从图分类器中删除，添加新分类器，放大和缩小，显示关联，删除关联等...该模型未更改，因为我没有创建任何新模型信息，我只是使用它们。

打开包的图并能够在类图中直接读取有关该类应该是什么的注释，这确实很重要。该方法应该执行的操作以及流程等...

UML很棒，确实很有帮助，但是我们应该停止使用模型驱动开发，以便在建模/开发阶段提供更大的灵活性和更多的迭代。类图是从代码实时更新的，文档始终准确无误，只需单击即可获得。我不会提及工具，但是如果您使用Java和Eclipse，很容易找到我使用的工具:-)