文档降级-如何处理？

重要提示：我们有没有问题，有任何的源代码文件。这属于常规代码审核，并且是最新的。我们的问题是开发人员文档（如果愿意，也可以是“外部”），从程序员到程序员的类似博客的小技巧，这些技巧往往一经编写，经常被抛在后面。

我们使用类似Wiki的系统来生成程序员文档 - 程序员为程序员编写的文章，详细描述了特定代码的工作方式。这些维基页面通常包括：

• API部分设计决策背后的动机（例如；我们做这件丑陋的事是因为这个特定的第三方库希望以这种方式完成工作，因为另一个库...是因为...）
• 解释我们如何处理特定的常见任务（例如，显示琐碎的弹出窗口，该弹出窗口需要引用适当的应用程序样式，在注册表组件中注册自己，并实现一些接口以便被其他组件自动“扫描”）
• 良好做法（实际上是主观的，我们确实将这些内容记下来了）
• 环境配置，所需的工具及其设置

通常，主要与编写代码有关的内容由于其大小和博客文章/类文章的性质而与常规代码文档不符。

问题

就几个月前引入这个系统而言，似乎是个好主意，如今，我觉得它引起的问题比解决的问题多。例如：

• 人们确实写文章...但是一旦代码更改，Wiki更新就很少跟进
• 很多草稿文章，是某人匆忙写的，像这样离开
• 即使文章请求通常来自项目负责人，也几乎从未对其正确性/组成进行过验证-有时会导致质量不佳

通常降解。代码已更改，Wiki保持不变。下次有人寻找信息时，他通常会发现一堆过时，质量低下的东西-并且想知道正在发生什么，他发现的东西是准确的还是（甚至更糟）其中的哪些部分。而本该提供帮助的结果却相反。

目前看来，人们已经意识到了这个问题，包括项目负责人，但是显然没有人愿意为此做任何事情（或者要做更多有趣的事情）。

我最初的想法是将其全部遗忘（在我连续几次被过时的“小费”咬伤之后），但是我想那可能太极端了。一些信息值得注意，有时会读得很好，但是问题仍然存在：如何处理其“最新信息”？它是否以某种方式链接到源代码（因此，当检入文件的更新版本时，文章作者会收到通知，他可能需要修改代码/文章）？有指定人员在日常基础上“监视”它吗？定期清理吗？

听起来您在Wiki中记录了太多琐事。

文档代码块和代码中的方法。尝试使您的代码具有自记录性，因此您不必进行大量注释。编写单元测试也可以提供帮助。

在Wiki中以更高的粒度记录设计决策和体系结构，因此Wiki无需经常更改或进行大量工作即可更改。如果您团队中的很多人已经知道架构，并且团队没有迅速发展，那么可能根本没有足够的文档来记录他们，面对面的交流通常是最好的知识转移。

立即重写或删除过期信息，例如死代码，保留的时间越长，发现就越困难，并且积累的越多。如果您没有时间，只需将其删除并将文章标记为需要返工，它将使您变慢，并且仍然存储在版本控制中。

通过在脚本或安装文件中自动执行过程来记录过程。否则将它们保留在Wiki中，但是每次有人使用Wiki中的过程时，请告诉他们尝试改进文章或使过程的某些部分自动化。

博客文章属于博客。如果人们想分享他们的个人意见和建议，请为此创建一个公司博客。他们可能不希望自己的文章被修改，也没人会对其进行修改，所以不要让他们弄乱Wiki。

文档应被视为可交付成果，因此应遵循可追溯性和接受性规则，并有适当的开发时间。

看到人们“期望”软件文档成为事实的情况并不少见，而并非如此。

激进但有效。如果有人编写了一个新模块但没有记录下来，请在问题跟踪器中重新打开该任务，如果有必要，请阻止运送所有未记录的源代码。如果您允许开发人员将源代码文档视作必要的恶作剧，那么您将得到零碎而过时的文档碎片。

在我最近的项目中，我们倾向于至少跟踪所有必需的第三方库。如果有人介绍了新库，但没有记录，则我们回滚解决方案，直到介绍了文档。如果没有这种激进的方法，将会造成混乱。例如，没有经验的开发人员可以使用其许可证与我们的软件许可证冲突的库。

如果某些事情快速变化，则不应在代码之外进行维护。

API部分设计决策背后的动机

这对于保持与代码的接近尤其重要。如在同一源文件中。这样，无论何时有人触摸文件，都将很难忽略，并且不知道外部文档存在的人员向TheDailyWTF提交的提交也将减少。

通常降解。代码已更改，Wiki保持不变。

这就是“可执行文档”（单元测试）变得非常有用的地方。如果代码更改并且测试没有随之更改，则构建将中断。当然，将测试编写为文档需要一些技巧。但是编写（好的）外部文档也是如此。

解决问题的一种好方法是使其成为过程的一部分。如果您有跟踪到/参考Wiki上相关页面的代码，则开发人员可以轻松地找到可能需要更新的内容。另外，请审阅者对代码进行审阅，以确保Wiki是最新的（关于更新）。

作为流程一部分添加它的另一种方法-由于您使用的是敏捷模型，因此是迭代计划过程的一部分，可以是更新Wiki中计划的更改。Wiki然后用作“这就是事情应该如何工作”资源。

如果您使用的是.net语言，请查看（Sandcastle），它使用XML文档（在C＃中为//），并将其转换为MSDN帮助格式。

该格式包括描述，注释，并且能够包含代码示例以及某些其他功能。您可以输出为.CHM，.HsX，.MSCH和HTML / ASP.NET格式。实际项目已添加到您的解决方案中，并在构建服务器上构建。我们已经做到了这一点，并在每个发行版中都将其部署到网站上，并且消费者喜欢它，因为文档与发行版相关，并且会不断更新。

您还可以指定要包含在文档中的内容。当前，我们有2个项目：一个用于外部消费者，仅包括合同和适当的项目（类，枚举等），另一个用于内部开发人员，其中包括API中的所有内容，包括私有和内部标记的项目。

这已成为我们使用的唯一文档，因为使用API​​的动机和怪癖可以包含在文档的“注释”部分中。在我工作的地方，该过程运行良好。

我将集中在两个方面，1）代码。2）无代码注释和文档。

1）代码。

尝试使其成为自我文档。在过去，我发现这通常是建议性的，但很少得到很好的解释，所以...

代替这种伪代码：

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

执行看起来更像这样的代码：

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

使用源代码管理来跟踪“谁在什么时候做了什么”信息。

2）非代码

使用Wiki和markdown格式来维护此信息。使它成为工作的一部分。公开发布，发布并发布博客。设置标准的每周或每月会议，以审查新旧内容。提出一个口头禅：当有人问某事时，给出答案...以及“下次有人问这个问题应该出现在Wiki中吗？”的想法。