我花了很大一部分专业工作时间阅读技术文档。 也许“通读”并不是描述它的正确方法。 在这一点上，它更像是快速扫描菜单，常见问题解答和段落标题，以获取在哪里可以找到所需确切信息的线索。 除了某些例外情况，无论是我只是想快速确认正确的命令行语法，还是想让自己了解一种全新技术，这种情况都很常见。
基于Web的技术文档：性能不佳的艺术
现在，我对那些提供详细语法指南和手册页的人没有任何抱怨-他们为什么要重新格式化整个文档以突出一些我可能有一天会去寻找的晦涩细节？ 但是，当我试图向自己介绍一个复杂的软件包时-要弄清其目的和主要用例-那么我有理由期望有一个相对可预测且舒适的实现目标的途径。 取而代之的是，我经常遇到一个项目主页，其中包含指向多个目标的链接，这些目标的名称为“入门”，“如何使用…？”，“文档”，并深深地埋在几个菜单层的“快速入门指南”下。
通常，我发送到的页面不完整，显然是改变主意和预算超支的受害者。 其他将涵盖该软件的过时版本，这些过时版本可能具有与最新版本明显不同的功能集。 更糟糕的是：这些功能实际上可能仍然存在，但是从那时到现在，它们已经更改了名称甚至图标。
即使我们忽略了写作的质量（控制起来可能非常困难且成本高昂）和单个文档的可理解性，似乎经常还会出现重大的版本控制和项目管理问题。 我通常可以猜测发生了什么：一些客户抱怨说他们无法弄清楚如何使用该软件，因此管理层（无法自行正确评估文档的当前状态）命令从头开始创建一套完整的新软件。 。 该项目开始了，但是大约一半的时间里，主要贡献者要么离开了公司，要么因其他截止日期和需求而分心。
直到有更多的客户抱怨他们也无法弄清楚如何使用该软件，才坐下来。 冲洗。 重复。
糟糕的文件记录总是邪恶的吗？ 绝对不。 考虑到开源项目通常使用的有限资源，我经常为这些开源项目能够完成多少而感到惊讶。 而且，无论如何，只要像我这样的人不自愿提供帮助，我们就无权抱怨。
所有文件都是邪恶的吗？ 不。 尽管您可能会说有太多的说法，但是Amazon的AWS维护着庞大的文档资源，该文档资源精心编写，精心设计并且在整个系统中井井有条，以至于可以在任何给定页面中查找元素是可预测的且快速的。 AWS并不是唯一的成功案例，但也不完全是人满为患的领域。
技术书籍：性能过高的艺术
在文档连续性的另一端是书籍。 还记得那些吗？ 尽管我可能多年没有购买技术书籍，但无数人一直在这样做。 实际上，至少在短期内，技术出版业看起来非常健康。
更好的传统出版商将对书的建议书进行非常仔细的分析，然后再得出结论，这个想法是有道理的，并且有足够的读者感兴趣以使其有价值。 一旦开始写作，他们将在书籍制作的每个阶段投入层层的编辑和审阅者。 并且当他们用完所有编辑器时，他们将进行编辑委员会审查，以确保这不是一个可怕的错误。
这就是曼宁（Manning）的编辑们在我的书上做了如此出色的工作的方式。 这也与我与Pluralsight团队制作视频课程的过程非常相似。
正确完成后，系统会在主题，样式，章节甚至段落级别创建检查点，询问是否需要，是否已显示此元素，并将其正确地放入更大的视野中。 这些检查点造就了不错的书，但它们往往非常昂贵。
过度吗？ 有时。 对于基于Web的文档项目，成熟的多层编辑系统是否可以负担得起？ 也许并非总是如此。
但是创建高质量，易读且组织良好的文档对于许多公司来说是一项重要的业务需求，因此对于他们来说，至少将他们已经得到的内容提交给具有以下知识的人员进行彻底审核可能是一个非常好的主意：经验，技术知识，以及最重要的是客观性。 很有可能会导致使用更多有用的文档产品。 是的：文档也是产品。
大卫·克林顿（David Clinton）将许多商品 停放 在 Bootstrap-IT.com上 。 您可能会惊讶于那里的发现……
