关于文档,敏捷宣言说:
我们已经重视工作软件,而不是全面的文档
并且我同意。 如果您可以在工作软件和文档之间进行选择,我可以随时选择该软件。 但是正如我之前注意到的,人们似乎在读上面的引文
我们不重视全面的文档
在其他情况下,有些文档似乎并没有增加太多价值:
奥利弗·吉尔克(Oliver Gierke)在演讲中提到“哇! 我的建筑去了哪里?” 使您思考的体系结构文档:THAT系统的文档如何最终出现在THIS系统的文档中?
马库斯·加特纳(MarkusGärtner)讨论了与实际存在的流程不符的流程文档。 他甚至意识到,它不适合现实,因为现实是复杂的。 马库斯(Markus)也引用了与瑞士军方的事实不符的文件:
如果地图和地区不同意,请始终相信该地区。
但是我猜瑞士军仍然使用地图吗? 为什么?
因此,这是我的清单,说明您可能希望拥有(或创建)地图的原因,尽管它会与该地区产生分歧。
新指南
您可能不需要居住区域的地图。您知道所需的所有街道和路径。 您甚至还知道没有地图知道的小捷径。 但是,如果您住在未知地区的酒店,地图对您的游览非常有帮助。 这同样适用于您的系统。 使用该系统的开发人员可能会很了解重要的部分,但是如果有某种地图可以帮助他,一位新的开发人员将不胜感激。 当然,人工指导通常会更好,但是指导成本很高,而且并不总是可用。 因此,在这种情况下,即使他的地图与该地区存在分歧,地图也具有很大的价值,因为它始终会有些过时并且会简化事情。
10000英尺视角
即使您非常了解该区域,有时也不容易确定2点之间的最短,最快或最节省路径。 地图可以帮助您。
规划版图的样子
当地图和领土不一致时,这可能是因为地图已过时或完全错误,但是也许它描述了领土将来的样子? 在美化环境和软件开发中,我们积极地改变环境。 当许多人为此必须一起工作时,制定某种计划当然会有所帮助。
解释为什么领土看起来像它
有时您会遇到景观特征,但根本不清楚为什么存在该特征 。 带注释的地图可以澄清这是否只是等待删除的垃圾,是因为创建它很有趣吗? 还是真的重要?
因此,地图(以及软件开发项目中的文档)确实可以达到某些目的。 但是为什么他们会受到如此糟糕的报道呢? 那你怎么改变呢?
明确预期目的
如果您尝试使用描述该领土一年后的样子的地图进行导航,那么您将遇到麻烦。 如果您使用概览图以了解某些微小细节的目的,则同样适用。 创建文档时,问自己要解决什么问题。 在文档中明确说明文档应解决的问题,最后在文档中解决该问题。
保持文件最新
过时的文档仅对考古学家和历史学家有意义。 两者在软件开发项目中都很罕见。 创建文档时,请始终考虑如何确保文档保持更新。 也许您将其添加为“完成的定义”的一个点,也许您要定期安排一些时间。 首选易于更新的文档方式。 Wiki很棒,作为文档的代码更好。 如果您需要漫长的时间来批准对文档的更改,则可以放心,如果不强迫他,则没人会对其进行更新。
使用您的文件
如果不使用文档,显然是无用的。 如果您自己不使用文档。 您为什么认为其他人会呢? 使用您的文档将使您意识到它的问题,因此可以对其进行修复。
使其易于访问
一些文档的存储方式类似于拆除Athur Dents房屋的计划 :它们在计划办公室中显示,无论如何,任何人都不会去,在没有灯光或楼梯的地窖中,锁在废弃厕所的文件柜中。
如果有文档(或文档的重大更新),请告诉所有人。 然后将其打印并粘贴到办公室的墙上。 在所有相关人员都可以看到它的地方放置一个链接(例如,在CI服务器的主页上)。 确保有一种简单的方法来获取有关更改的更新(例如通知邮件或RSS feed)。
不要混淆工具和目的
文档是一种用于建立相互理解的工具,只有在确实有助于实现相互理解时才应创建文档。 文档本身并不是目的。
翻译自: https://www.javacodegeeks.com/2013/08/the-purpose-of-documentation.html