文档是共享词汇表的表达,因此它应该从史诗一直到代码中的注释一致:
文档应该是全面的,可以理解的。建议使用示例。
功能故事,技术故事,伪代码和断言之间的语言应该具有命名约定
人们不知道的功能是无用的功能。
缺乏文档可能是缺乏营销计划的症状
未记录的功能是无用的功能。新功能的补丁必须包含文档。
缺乏文档可能是缺乏可用性,可访问性和信息体系结构的症状
调整文档。首先这样做会给你一个如何印象 您的更改会影响用户。
缺乏文档可能是缺乏对用户和维护者的关注的症状:
软件本身并没有用。可执行软件只是图片的一部分。没有用户手册,业务流程,设计文档,评论良好的源代码和测试用例,这是没有用的。这些应该作为开发的内在部分产生,而不是最后添加。特别要认识到,设计文档有两个不同的用途: 允许开发人员从一组需求到实现。这类文档中的大部分在实现后都超过了它的实用性。 允许维护人员了解实现如何满足要求。针对维护者的文档比传统的设计文档更短,更便宜,更有用。
软件本身并没有用。可执行软件只是图片的一部分。没有用户手册,业务流程,设计文档,评论良好的源代码和测试用例,这是没有用的。这些应该作为开发的内在部分产生,而不是最后添加。特别要认识到,设计文档有两个不同的用途:
允许开发人员从一组需求到实现。这类文档中的大部分在实现后都超过了它的实用性。
允许维护人员了解实现如何满足要求。针对维护者的文档比传统的设计文档更短,更便宜,更有用。
了解任何项目的目的需要在项目时间表和源代码历史之间建立关系:
写下更改的更改日志条目。这既是为了节省我们编写它们的额外工作,也是为了帮助解释您的更改,以便我们能够理解它们。 更改日志的目的是向人们显示在哪里可以找到更改的内容。所以你需要具体说明你改变了哪些功能;在大型函数中,指示函数在变量中的位置通常很有帮助。 另一方面,一旦您向人们展示了在何处找到更改,您无需在更改日志中解释其用途。因此,如果你添加一个新函数,你需要说的就是它是新的。如果你觉得目的需要解释,它可能会 - 但是将解释放在代码中的注释中。那里会更有用。
写下更改的更改日志条目。这既是为了节省我们编写它们的额外工作,也是为了帮助解释您的更改,以便我们能够理解它们。
更改日志的目的是向人们显示在哪里可以找到更改的内容。所以你需要具体说明你改变了哪些功能;在大型函数中,指示函数在变量中的位置通常很有帮助。
另一方面,一旦您向人们展示了在何处找到更改,您无需在更改日志中解释其用途。因此,如果你添加一个新函数,你需要说的就是它是新的。如果你觉得目的需要解释,它可能会 - 但是将解释放在代码中的注释中。那里会更有用。
的 参考 强>
Vim文档:开发
SCRUM-PSP:拥抱流程敏捷性和纪律(pdf)
安全的软件开发生命周期过程| US-CERT
不安的婚姻?合并Scrum和TSP(pdf)
TSP / PSP和Agile-SCRUM:相似之处&差异
GNU Emacs手册:发送补丁
我认为在你想要应用敏捷之前,有必要首先澄清你对使用敏捷的需求。
敏捷是高度不可预测的域的推荐工作框架(您也可以检查Cynefin模型以识别您的工作环境)。在这个领域,您需要“工作软件”和“良好的沟通”,以便在短期迭代过程中审查和修改您的开发。因此,您可以根据软件的反馈更改和改进软件。事实证明,这是在竞争激烈的商业世界中构建软件的最有效和最有效的方式。
但是,在您的组织中,您使用有限的文档维护旧版软件。这种情况与敏捷的设计完全不同。您需要在您的世界中进行优化,而不是测试或寻求增长。简而言之,流程/工具和文档更重要。
关于电子邮件通信,毫无疑问,电子邮件可以达成交易,但您永远无法通过电子邮件进行交易。它与您应用敏捷的方式相同。您应该根据不同的情况同时应用面对面和电子邮件。
我认为敏捷不仅仅是一种方法论,而是一种框架。这个概念允许您根据自己的工作环境构建自己的流程。
综合文档有时被视为证明进展的一种方式。 “如果我们有详细的规格和重量级的设计文件,那么我们在产品交付方面取得了很大进展”
什么 工作软件综合文档 意味着我们将工作软件视为比文档更好地展示进展。这是因为全面的文档可能会给出错误的信心。
所以没有什么可以说避免做任何文档。这只是说我们应该 只做必要的文档,而不仅仅是做文档,因为它是一个过程的一部分 。
在您的软件难以使用的示例中,可能会有更多文档 需要 。只是不要写那些永远不会被使用并且价值不大的文档。
与其他形式的通信相比,面对面通信具有许多优点。例如:
请注意,敏捷宣言并未提及面对面的沟通。它只是说 个人和互动 。如果您和您的团队有与面对面沟通一样有效的沟通方式,那么这种方式与敏捷方法一样。重要的是我们重视互动并让团队成员彼此密切合作。
在考虑所有敏捷建议后,您在问题中没有提到任何问题。工作软件还应具有良好的代码标准和设计。
关于缺乏文档单元测试(TDD / BDD)的特定问题可能非常有用。良好的代码覆盖率可以解释代码应该如何比详细的文档更好地工作。敏捷方法也欢迎简单,因此您的整个架构可能过于复杂
关于面对面交流。想象一下当您在产品中检测到问题时的情况(网站标记)。您只需前往坐在您房间内的前端开发人员或拨打Skype电话并开始解释问题,而不是使用重复和附加屏幕截图的步骤编写长电子邮件。开发人员很快意识到他忘了包含一些脚本。因此,您可以在几分钟内得到答案,而您的电子邮件可在第二天得到解答