敏捷 技术文档_持续建立文档–选择敏捷方式

敏捷 技术文档

最近，我想知道记录项目的最佳方法是什么？

我的文档经验在不同的工具和方法中有所不同。

我想分享一些看法，以及关于记录项目最佳方法的结论。

该文档可以分为以下几类：

文档位置：

• 内联代码/版本控制系统（通过代码提交描述）
• 在单独的服务器上链接到代码
• 在单独的服务器中，与代码分离（没有直接链接）

文档完成者：

• 开发者
• 产品团队/设计团队/建筑师
• 技术作家

文档也：

• 集成开发环境
• 设计文件
• 建模工具，流程
• 维基
• 版本控制（例如git，svn等）提交
• 接口文件

毫不奇怪，所使用的工具，编写代码的人员，文档的数量，文档与代码的“距离”与该文档的准确性之间存在直接的关联。

鉴于以上类别，可以通过以下方式进行组织：

• 开发者
• • 内联代码/版本控制系统（通过代码提交描述）
  • • IDE /版本控制

• 产品团队/设计团队/建筑师
• • 在单独的服务器上链接到代码
  • • 设计文档，接口文档

• 技术作家
• • 在单独的服务器中，与代码分离（没有直接链接）
  • • 建模工具，Process Flo，Wiki

开发人员倾向于使用IDE编写简短的内联文档，良好的接口语义和互补的编写良好的代码。

只要编写该功能的人员与代码之间的距离更大，那么文档通常将位于与代码存在的地方更不相关，更全面的位置。

根据我的经验，即使是好的设计也可能会有所改变，即使文档很好但与代码分离，大多数机会是它不会赶上代码更改。

在现实生活中，当需求不断从业务进入开发时，有时它不仅会带来直接支持功能的附加代码，而且我们经常会看到需要进行一些结构或基础更改和重构。

内联代码文档是敏捷的，并且随着功能的更改而花费最少的精力进行更改。 如果开发人员提交按功能分组的代码并提供有关所做更改的良好解释，则它将提供最新，最准确的文档。

我知道你们中有些人可能会对重型设计或复杂的功能文档感到好奇。

我建议尽可能内联代码解决这些问题，例如，假设您在网络上阅读了某种模式或某些错误解决方案，则在实现该解决方案的方法/类附近放置了指向该解决方案的链接。 尝试通过已知的模式对代码进行建模，从而避免编写文档。 尝试使用约定，以减少配置量并使代码流更可预测和可发现。

当以敏捷方法论管理项目时，这种方法甚至更为重要。

通常，这种方法会直接与产品/业务进行沟通以了解需求，而不是记录在案的PRD。 这使得使代码自说明易于定向变得更加重要。 而且，频繁的设计变更和业务变更将导致解耦的文档很快过时（或将导致难以维护）

尽管听起来说起来容易做起来难，而且并不是每个项目的灵丹妙药，但是在开发项目时，应将编写尽可能接近代码本身的文档作为准则/理念。

参考： 持久地建立文档–在Gal Levinsky博客博客中，从我们的JCG合作伙伴 Gal Levinsky 选择敏捷方法 。

翻译自: https://www.javacodegeeks.com/2012/08/build-documentation-to-last-choose.html

敏捷 技术文档