文档加载完成覆盖

程序或文档是哪一个？ 困境就在这里。

我认为我从未听过有人说过“此文档很棒”。 通常，我听到某些特定文档的糟糕程度，并且我重复了多次，以免使自己陷入困境。

但是，那里有很多非常好的文档。 例如，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哲学的 Tenet 5是“将数据存储在纯文本文件中”。 该程序违反了这一宗旨。 因此，当程序升级未能正确升级存储数据的数据库时，几年来我一直无法访问客户注释。

我现在仍然违反该宗旨，即使不是精神，因为我现在将笔记存储为开放文档格式（ODF）。 但是，ODF是一种众所周知的开放式文档格式，并且有许多应用程序可以使用它。 尽管原则专门针对程序数据，但我认为必然的结果是，文档应以ODF等开放格式进行维护。

无论您做什么，但是无论选择哪种工作，都请记住，直到完成文档后才完成该工作。

翻译自: https://opensource.com/business/15/6/documentation-dilemma

文档加载完成覆盖