在 2016 年南加州 Linux 展会 (SCaLE 14x) 上，资深技术作家兼编辑 Bob Reselman 将发表题为 创建世界一流技术文档的 7 条规则，v.2016 的演讲，该演讲基于 他六年前写的一篇文章。在本次采访中，他对这些规则进行了更新，并谈到了人们对项目文档的态度正在发生怎样的变化。
如果今天您是第一次撰写这篇文章，您还会提出相同的 7 条创建世界一流技术文档的规则吗？还是说这些规则自那时以来有所演变？
嗯，以下是 7 条规则
- 枯燥乏味令人厌恶。
- 在开始之前，请明确您希望读者在阅读完后做什么。
- 始终按照结构清晰的提纲进行写作。
- 避免使用含义模糊的代词。
- 清晰 = 插图 + 文字
- 在处理概念时... 逻辑插图和示例。
- 接受修订。
对我而言，演变最大的规则是第 1 条：枯燥乏味令人厌恶。最初撰写这些规则时，我极力主张使用幽默来避免枯燥乏味。但现在我的想法有所改变，我认为引人入胜的内容可以使作品不枯燥。是的，我们有些人仍然喜欢幽默。但随着我在这方面的工作越来越多，我发现清晰、重复的书写，并使用有吸引力、准确、易于理解的插图，可以消除技术文档领域中的许多枯燥乏味之处。
您在开源项目文档中最常见的错误是什么？
这个问题对我来说很难回答。好的方面比不好的方面要多得多。我认为 Read.ME 文件的重要性和突出性，以及 markdown 使得一致、有用的技术文档成为开发社区的一种生活方式。是的，事物会变得陈旧，这对于任何文档来说都很常见，但总的来说，基于文本的文档的整体趋势是向上的。
哪些项目的文档特别出色？哪些项目可以从文档大修中受益？
我真的无法指出任何一个项目，因为项目太多了。但在商业工作方面，我认为 New Relic 的人做得很好。他们有一个结构良好的分类法和内容来支持它。该公司制作简短、有用的视频，直奔主题。
此外，Akka.Net 也做得令人印象深刻。文本文档在视觉上清晰且组织良好。每页文档都在左边距显示提纲结构，因此您可以通读或挑拣选择。他们显然对事物进行了规划。他们非常注重让人们尽可能轻松地使用他们的技术。
当然，就展示大量文档的能力而言，您不得不佩服 AWS 所做的工作。在 HowTos 方面，他们在 UI 的视觉展示方面仍然有些欠缺，但总的来说，他们确实设法捕获并呈现了一个巨大的分类法，这个分类法还是很有用的。
您是否看到多年来人们对项目文档以及编写文档的人员的态度发生了变化？
对于大型公司和工具提供商而言，文档始终在变得越来越好。形势的经济性要求他们尽一切努力让他们的用户群感到满意。然而，对于规模较小的中型公司，尤其是那些拥有 IT 部门而不是软件开发部门的公司，我没有看到我所希望的那种进步。任何生产软件或系统的公司都应该配备一名技术编辑的观念仍然很难推销出去。要么是希望有一天他们会聘请一位专职技术作家来使一切变得更好，要么是他们认为当前软件开发人员的文档工作已经足够好了。虽然所有内容创作都需要由主题matter expert 生成，但一位优秀的技术编辑可以教内容创作者如何更有效率。此外，技术编辑了解全局，即需要满足的知识库的整体分类法，以及使工作在短期和长期内保持一致的风格指南。
然后是视频作为文档资源的持续兴起。我将在7 Rules 2016 演讲中大量谈论视频。还有很多工作要做。
我有一个愿景：2016 年将成为开源俳句年。您对文档的建议是什么，以俳句的形式给出？
我们所珍视的，
应该妥善记录，
令人愉快地记录。
4 条评论