文件目的

关于文档，敏捷宣言说：

我们已经重视工作软件，而不是全面的文档

并且我同意。 如果您可以在工作软件和文档之间进行选择，我可以随时选择该软件。 但是正如我之前注意到的，人们似乎在读上面的引文

我们不重视全面的文档

在其他情况下，有些文档似乎并没有增加太多价值：

奥利弗·吉尔克（Oliver Gierke）在演讲中提到“哇！ 我的建筑去了哪里？” 使您思考的体系结构文档：THAT系统的文档如何最终出现在THIS系统的文档中？

马库斯·加特纳（MarkusGärtner）讨论了与实际存在的流程不符的流程文档。 他甚至意识到，它不适合现实，因为现实是复杂的。 马库斯（Markus）也引用了与瑞士军方的事实不符的文件：

如果地图和地区不同意，请始终相信该地区。

但是我猜瑞士军仍然使用地图吗？ 为什么？

因此，这是我的清单，说明您可能希望拥有（或创建）地图的原因，尽管它会与该地区产生分歧。

新指南

您可能不需要居住区域的地图。您知道所需的所有街道和路径。 您甚至还知道没有地图知道的小捷径。 但是，如果您住在未知地区的酒店，地图对您的游览非常有帮助。 这同样适用于您的系统。 使用该系统的开发人员可能会很了解重要的部分，但是如果有某种地图可以帮助他，一位新的开发人员将不胜感激。 当然，人工指导通常会更好，但是指导成本很高，而且并不总是可用。 因此，在这种情况下，即使他的地图与该地区存在分歧，地图也具有很大的价值，因为它始终会有些过时并且会简化事情。

10000英尺视角

即使您非常了解该区域，有时也不容易确定2点之间的最短，最快或最节省路径。 地图可以帮助您。

规划版图的样子

当地图和领土不一致时，这可能是因为地图已过时或完全错误，但是也许它描述了领土将来的样子？ 在美化环境和软件开发中，我们积极地改变环境。 当许多人为此必须一起工作时，制定某种计划当然会有所帮助。

解释为什么领土看起来像它

有时您会遇到景观特征，但根本不清楚为什么存在该特征 。 带注释的地图可以澄清这是否只是等待删除的垃圾，是因为创建它很有趣吗？ 还是真的重要？

因此，地图（以及软件开发项目中的文档）确实可以达到某些目的。 但是为什么他们会受到如此糟糕的报道呢？ 那你怎么改变呢？

明确预期目的

如果您尝试使用描述该领土一年后的样子的地图进行导航，那么您将遇到麻烦。 如果您使用概览图以了解某些微小细节的目的，则同样适用。 创建文档时，问自己要解决什么问题。 在文档中明确说明文档应解决的问题，最后在文档中解决该问题。

保持文件最新

过时的文档仅对考古学家和历史学家有意义。 两者在软件开发项目中都很罕见。 创建文档时，请始终考虑如何确保文档保持更新。 也许您将其添加为“完成的定义”的一个点，也许您要定期安排一些时间。 首选易于更新的文档方式。 Wiki很棒，作为文档的代码更好。 如果您需要漫长的时间来批准对文档的更改，则可以放心，如果不强迫他，则没人会对其进行更新。

使用您的文件

如果不使用文档，显然是无用的。 如果您自己不使用文档。 您为什么认为其他人会呢？ 使用您的文档将使您意识到它的问题，因此可以对其进行修复。

使其易于访问

一些文档的存储方式类似于拆除Athur Dents房屋的计划 ：它们在计划办公室中显示，无论如何，任何人都不会去，在没有灯光或楼梯的地窖中，锁在废弃厕所的文件柜中。

如果有文档（或文档的重大更新），请告诉所有人。 然后将其打印并粘贴到办公室的墙上。 在所有相关人员都可以看到它的地方放置一个链接（例如，在CI服务器的主页上）。 确保有一种简单的方法来获取有关更改的更新（例如通知邮件或RSS feed）。

不要混淆工具和目的

文档是一种用于建立相互理解的工具，只有在确实有助于实现相互理解时才应创建文档。 文档本身并不是目的。

参考：来自Schauderhaft博客的JCG合作伙伴 Jens Schauder 的文档目的 。

翻译自: https://www.javacodegeeks.com/2013/08/the-purpose-of-documentation.html