持续集成和持续交付文档_文档是另一个可交付成果和其他7条规则

持续集成和持续交付文档

我们（程序员）有文档在耳边。 建筑文档，设计文档，用户指南，功能规范，程序规范等等。 大多数文档比没用的文档更糟糕，因为它给人一种幻想，即所有内容都被记录下来，任何人都可以（几乎）随时学到任何东西。

一些文档已经过时了。 最糟糕的是由与编码人员生活在同一宇宙中的建筑师编写的。 官方体系结构和设计文档中描述的系统与实际代码几乎没有任何关联，但是由于（五位）架构师从未查看过这些代码，因此（十二位）程序员可以做他们喜欢的事情。

文档不会挽救我们。

但是，我也知道一些文档不仅有用，而且非常有价值。 有时，《用户手册》可能非常有用。 有时，开发人员“粗略指南”可以提供重要的见解。

那么，您如何区分差异？

您怎么知道该写什么，该放弃什么？

规则1：文档只是另一个可交付成果

花在编写文档上的时间不是花在编码，测试，分析或喝咖啡上的时间。 没有文档童话，而且文档远非免费。 写的成本和读的成本要高得多（如果曾经读过的话）。

因此，应像对待其他可交付成果一样对待文档。

如果有人想要一个文档，让他们请求它，并优先处理所有其他可能要做的工作。 如果有人准备替换其他工作以备文档，那是值得做的。

规则2：文件应增加价值

如果不增加系统价值，是否会向系统添加功能？

文档也是如此。 如果它增加了价值，那么就有各种理由去实现它；如果没有，那么为什么要花时间呢？

规则3：如果文件未完成，谁会投诉？

如有疑问，请确定如果未完成文件将投诉的人。 该人在文档上重视价值。 也许他们为新功能争辩他们的文档。

规则4：不要为了文件而写文件

不要仅仅因为某个地方的某个流程标准说需要编写文档而编写文档。 有人应该能够说出该标准，并解释为什么它比做其他事情更有价值。

规则5：基本文件是要做的工作的一部分

有些文件很有价值-如果有人缺席，有人会抱怨！ 用户手册是一种经常发生的情况。 我还与需要将文档作为联邦药品管理局（FDA）等法规包的一部分的团队合作。

如果一项工作需要更新文档，则更新文档是工作的一部分。 例如，假设您要向受FDA监管的系统中添加功能。 并假设FDA法规要求在用户手册中列出所有功能。 在这种情况下，添加功能的一部分工作就是更新用户手册。 将提供编码，测试和文档。 如果尚未更新《用户指南》，则该工作无法完成。

您不需要单独的用户故事来编写文档。 在这种情况下，文档可能构成完成定义的一部分。

规则6：做比您认为必要的少一点的事情

如果您交付的数量不足，那么有人会抱怨并且您需要对其进行重新处理。 如果没有人抱怨，那你为什么要这么做？ 它有什么价值？ –下次不要做！

这是一个旧的XP规则，也适用于其他地方。

规则7：不要指望任何人阅读您所写的内容

阅读文档非常昂贵。 大多数开始阅读此博客文章的人很久以前就停了下来，但您是个例外–谢谢！

文档也是如此。

文档越长，被阅读的可能性就越小。
而且文档越长，记住的内容就越少。

您和我不具备JKRowling的写作能力，所以我们当中很少有人可以吸引读者这么长时间的注意力。

规则8：作者也学习

对于很多文档-这里包括写作，我自己的书，样式，博客等-真正的读者是作者。 写作的过程可以帮助作者，可以帮助我们构筑思想，可以帮助我们发泄怒火和挫折感，可以使我们合理化，可以为辩论做准备，等等。

因此，真正想要该文件的人，重视该文件的人，如果未完成该文件将抱怨的人以及从该文件中学到最多的人通常是作者。

翻译自: https://www.javacodegeeks.com/2017/09/documentation-another-deliverable-7-rules.html

持续集成和持续交付文档