编写文档_编写足够的文档

最新推荐文章于 2024-12-05 13:14:34 发布

danpu1174

最新推荐文章于 2024-12-05 13:14:34 发布

阅读量168

点赞数

CC 4.0 BY-SA版权

文章标签： java python linux 大数据人工智能

原文链接：https://www.javacodegeeks.com/2015/02/writing-just-enough-documentation.html

编写文档

经常与敏捷软件开发相关的误解之一是，敏捷团队不会编写任何技术文档。

我认为这种误解之所以如此普遍，是因为敏捷宣言指出，我们应该重视工作软件，而不是全面的文档。同样，由于我们中有些人从编写较长的技术文档中获得了经验，而这些文档在完成后并未阅读或更新，因此自然而然地认为所有技术文档都是浪费的。

但是，这是具有严重后果的谎言。如果您曾经尝试维护没有技术文档的应用程序，那么您将了解这些后果。

再一次，我们必须在两个错误的选择之间找到权衡。让我们开始吧。

写好的文件

在敏捷软件开发变得流行之前，我们花费了大量时间来编写较长的文档，这些文档在完成后未被任何人阅读。一个软件项目有很多文档是很常见的，但是大多数文档都是无用的，因为它们已经过时了。

显然，这些传统做法会造成大量浪费，并且在项目完成后编写遗弃的文档确实没有任何意义。肯定有更好的办法。

我们可以通过回答以下问题找到更好的方法： 什么是好的文档？

我认为一个好的文档可以满足以下要求：

它有一个需要其信息的“客户” 。例如：开发人员将应用程序部署到生产环境时需要部署说明。
它越短越好，但不要更短 。良好的文档会尽快向读者提供所需的信息。它不得包含可能会干扰读者的不必要信息，并且不得错过任何相关信息。
它是最新的 。

如果我们要编写满足这些要求的技术文档，则应遵循以下规则：

我们不应该编写仅因为过程需要而编写的文档。如果任何人都不需要从文档中找到的信息，则我们不应该编写它。
我们应该使文档尽可能的简洁。因为较短的文档更容易更新，所以这些文档更可能真正被更新。此外，由于较短的文档阅读速度更快，因此我们不会浪费阅读文档的人员的时间。
我们应该将文件放在需要的地方。例如：开发人员读取（和写入）的文档应提交给版本控制。这样，每个开发人员都可以访问它们，并且我们可以使用代码检查来确保在更改代码时更新这些文档。
提交给版本控制系统的每个文档都必须使用基于文本的格式来编写。我最喜欢的工作工具是Asciidoctor，但Markdown也是一个不错的选择。

让我们看一下具体示例，这些示例演示了这些规则的真正含义。

我们需要哪种文件？

如果我们想弄清楚哪种类型的文档对我们有用，我们必须遵循以下步骤：

弄清楚我们必须做什么。
找出我们需要什么信息，以便我们可以做这些事情。

如果我们考虑一个典型的软件开发项目或当前处于维护阶段的应用程序，则需要：

安装或部署我们的应用程序 。我们可以编写说明来描述如何安装（或部署）应用程序的说明。如果必须先安装其他应用程序，然后才能安装（或部署）应用程序，则这些说明必须说明我们如何安装所需的应用程序。
配置我们的应用程序 。如果我们的应用程序具有复杂的配置（而实际的应用程序通常会这样做），那么我们需要说明来描述如何配置我们的应用程序。编写此类指令的最简单方法是在应用程序的配置文件中添加注释，但是有时我们不得不编写描述最常见场景的其他“教程”。
更改其他开发人员编写的代码 。在更改一段代码之前，我们必须了解两件事：1）它应该如何工作，以及2）目前如何工作。技术文档无法帮助我们理解代码的工作原理，但必须帮助我们了解代码的当前工作方式。令人惊讶的是，我们可以编写必要的文档而无需编写单个文档。我们可以通过将Javadocs添加到类中并将测试转换为可执行规范来记录代码。
解决生产环境中出现的问题 。如果我们生活在一个完美的世界中，我们将确保我们不必两次解决相同的问题。但是，由于我们不能始终确保这一点，因此有必要确保我们能够确定常见问题并尽快解决。一种方法是创建一个描述这些问题及其解决方案的FAQ。每个FAQ条目都必须描述问题并提供识别问题所需的信息。它还应描述解决问题所需的步骤。解决新问题的人必须在FAQ中添加新的FAQ条目。
帮助新开发人员熟悉代码库 。如果我们的代码库具有良好的Javadocs和干净的测试，则不必编写新文档。但是，通常我们的代码库是如此之大和复杂，以至于很难理解全局。这就是为什么我们经常最终写出一个过时的体系结构规范文档的原因，因为没有人去更新它。我们可以通过使文档尽可能的薄来避免这种情况。如果必须编写体系结构规范，则可以编写一份文档，其中提供了总体体系结构的简要说明，模块及其职责，描述了跨领域的关注点（身份验证，授权，错误处理，验证和事务）。实现，并描述集成。

我尝试说我们应该始终编写这些文档，这有点容易想到。但是，这将是一个错误。