工作未完成，直到文档完成

先有程序还是先有文档？这就是两难之处。

我不认为我曾听任何人说过“这份文档太棒了”。我听到的更多是关于某些特定文档有多糟糕的抱怨，而且我自己也重复过很多次。

然而，确实有很多非常好的文档。例如，LibreOffice 的文档就非常出色。它包括多种格式的文档，包括 HTML 和 PDF，范围从“入门”到每个 LibreOffice 应用程序的非常完整的用户指南。

RHEL 和 CentOS 以及 Fedora（它们都是非常密切相关的发行版）的文档也是我在 IT 行业工作 40 多年来见过的最好的文档之一。

好的文档并不容易，需要时间。它还需要了解受众—不仅与文档的目的有关，还与预期读者的技术专长以及读者的语言和文化有关。Rich Bowen 在他的精彩文章《RTFM？如何编写值得阅读的手册》中对此进行了很好的阐述。

我遇到的问题是，许多管理者不认为文档是高优先级事项。文档可能会退居这些问题之后，而且我不仅仅是在谈论开发经理和新代码。

我曾参与过 IT 行业的许多方面。幸运的是，我工作过的大多数公司都认为文档不仅重要，而且对于手头的任务至关重要，无论该任务是什么。

我的理念是多年来我最好的导师灌输给我的：“工作未完成，直到文档完成。” 这意味着一切都必须记录在案。

客户文档

举个例子，我目前拥有一家小型有限责任公司，我通过它做一些咨询工作。在与客户合作时，我总是记录我与他们的互动以及我执行的工作。在某些情况下，我有多年的文档，涵盖了从我与他们的第一次联系到我在为他们做项目时发现的关于他们网络的信息、我为他们安装的硬件的详细信息、我在项目上的工作的详细信息，以及每次我安装更新的记录。我在这些记录中包含数据，例如网络图和网络 IP 和 MAC 地址表，以及关于每个节点功能的注释。我还保留了我编写的脚本的输出，该脚本列出了我工作的每个 Linux 主机的硬件和一些配置详细信息。

这些信息有多种用途。它给了我一个记录，以便我可以回顾并回忆起我所做的事情以及客户环境的结构——这对我是个记忆辅助。我可以使用它来支持我在需要时提出的额外工作建议。在与客户发生纠纷时，保留详细记录也可能很有用。

在为客户执行工作之前，我总是创建一个任务列表，这样我就不会忘记任何需要完成的事情。我在该列表上做笔记，然后在工作结束时，任务列表成为我执行的工作的文档的一部分，并由我在执行工作期间所做的笔记补充。

代码文档化

代码文档化需要不同的信息和不同的方法。

我做的第一件事是记录源代码，对我来说几乎总是 Perl 或 BASH 脚本。事实上，在几年前我接受的一份工作中，我需要维护大量预先存在的 Perl CGI 程序，这些程序用作复杂电子邮件管理前端的接口。代码还可以，但有点复杂，并且没有任何注释或任何形式的文档。

我的首要任务是修复不同 CGI 脚本中的一些错误。我首先开始阅读这些脚本，以确定它们实际上应该做什么。当我确定每段代码做什么时，我添加了注释，以记录我刚刚阅读和解释的代码。就在做这件事的过程中，我能够确定错误的原因并纠正它们。

在我完成注释每个 CGI 脚本的任务后，我可以简单地将注释复制到一个单独的 HTML 文档中，该文档就变成了—加上一些标题和解释性文本—我本应创建的文档的主体。

当我编写新代码或维护现有代码时，注释是我添加的第一件事。从注释开始，我可以概述我要编写的代码的结构。然后我可以编写代码来实现注释中描述的操作。

但我甚至一开始都不会完成所有的注释。我首先创建一个基本大纲，其中包含描述程序逻辑的注释的简要框架。然后我创建代码来实现该基本框架。然后我处理各个分支，首先注释它们，然后编写代码。

这就是我对开头提出的问题的答案。至少对我而言，文档是第一位的。我已经可以听到敏捷支持者的键盘在敲击他们的评论了。但在非常真实的意义上，我所做的就是敏捷，因为我只编写我需要的文档，及时编写代码。然后注释也成为外部文档。

并非所有人都希望以这种方式工作，或者会发现它像我一样适合他们的工作方式。创建代码和记录代码的方法与执行此操作的人一样多。只需做最适合你的方法即可。

问题

我自己的文档也遇到了一些问题。其中首要的问题是未能及时或完整地更新文档。当我需要的信息没有被正确记录时，这会导致问题。当我发现我的文档工作有所疏忽时，我会尽快回去纠正它。

文件兼容性也可能是一个问题。几年来，我使用了一些 Linux 软件，这些软件以一种不仅仅是纯文本的格式维护我的数据，并且在某种意义上是专有的，因为它没有文档记录，并且没有其他软件可以访问该格式。这至少部分是因为我没有意识到数据格式，这是我自己的错。

Unix/Linux 哲学的原则 5 是“将数据存储在扁平文本文件中”。这个程序违反了该原则。因此，当程序升级未能正确升级存储数据的数据库时，我无法访问几年前的客户笔记。

如果不是精神，我仍然违反了该原则的字面意思，因为我现在以开放文档格式 (ODF) 存储我的笔记。但是，ODF 是一种众所周知、开放且有文档记录的格式，并且有许多应用程序可以使用它。尽管该原则专门指程序数据，但我认为一个推论应该是文档应以开放格式（如 ODF）维护。

无论你做什么以及你选择如何工作，请记住，工作未完成，直到文档完成。