【IT168 评论】大多数程序员都非常在乎他们开发的软件的质量，但是他们却很少关注相应的文档。虽然很少有人提及这一点，但是一份好的文档确实能为你的软件的成功插上翅膀。没有好文档，大家不会用你的东西，没有好文档，大家很难喜欢你的东西。如果你能成功创造良好的用户体验，你那些高兴的用户们就会口口相传的为你的软件进行宣传——只有他们真正理解你的工作，他们才可以做到这一点——这就更不能没有一份好的文档了。

　　可惜，大多数开源项目并没有好的文档。他们令人失望的原因有几个方面。

　　我下面给出的例子并不是经过权威认证的，我也没有挑错的意思。我只是认为以下这些我最近用过的软件中，他们的一些东西我并不是十分认同。你可以看看我从那些或许是你最喜欢的软件当中发现的问题(不管你是开发者还是用户)，然后如果可以，我希望你能得到一点启发。

　　1.缺少一个优秀的简介

　　软件的简介可以给你的潜在用户第一印象。特别是当这个软件放到GItHub上的时候，简介货自动被展示在软件的主页上。如果你简介搞的很糟糕，或许你的用户就一去不复返了。如果你想一下子抓住用户的眼球，然后诱导他们使用你的软件，写个优秀的简介吧。

　　简介永远都是要解释点东西，他至少应当包含如下几点：

　　• 这个软件是干啥的

　　• 目标用户是谁

　　• 运行平台和硬件

　　• 依赖关系

　　• 如何安装

　　以上这些必须考虑哪些从来没有听说过你的项目的人的技术水平，他们可能从来没有接触过你的软件所涉及的项目。如果你的模块是用来计算Levenshtein distance(译者注：它指的是一种常用的衡量两个字符串之间相似情况的度量。它是编辑距离的最为广泛使用的一种定义，大多数情况下编辑距离被用来特指Levenshtein距离。所谓字符串A和B的编辑距离就是指一个字符串A需要经过多少次编辑可以得到字符串B。)别指望你的用户在读你的简介之前就对levenshtein distance有一定的了解。你最好解释一下，然后给那些想要深入了解的用户几个链接。

　　不要在简介中涉及其他的项目，比如“我这个玩意儿类似于另一个东西，但是比他好多了!”。这对于连你所涉及的那个项目都没有挺熟过的人来说：没有用。

　　2. 没有在线文档

　　虽然我还没有看到关于这方面的研究，但是我敢保证90%的文档查阅工作都是通过Google和浏览器在互联网上完成的。 你的的项目必须要有在线的文档。说到这里，我感动惭愧的是，我自己的项目ack居然 没有在大多数人用来查找文档的地方。我的这个推断是基于我自己的使用情况，也就是说，如果我想知道一个命令怎么用，我会查看它的man(手册)页。

　　为什么这会引起我的注意呢?因为，总会有用户发邮件来问我已经在FAQ中回答过的问题，他们不阅读我的FAQ文档令我很烦恼。 原来，他们在网络上查找，但是我却没有将FAQ发布在网上。犯这样的错误很容易，因为我熟悉这个项目，因此实际上我自己并不 使用FAQ，因此我没有注意到它们没有在线版。很多问题都来自同样的疏忽：作者并没有换位思考。

　　3.只有在线文档

　　与前一点想反，只有在线文档也是不好的。有些项目在完成时并没有同步打包放出符合规范的文档。

　　以搜索引擎Solr为例，它有一个非常完善的在线wiki文档。遗憾的是，可供下载的2200多页文档都是通过javadocs自动生成的。唯一的一份提供给用户的文档只是一个单页教程。

　　PHP语言包里并没有提供任何文档，如果你想要的话，你必须去指定的页面获取。更糟的是，只有核心文档才能下载，有些很有用的用户提交的注解文档(详见下面的“不接受用户的注解”)并没有提供给用户下载，而且他们并没有像在线文档那样易于查找导航。

　　你不能假设用户在需要文档的时候可以连接到互联网。飞行模式还是存在的。 即使如此，你也不能期待用户依赖于你的项目网站总是在线的。 在过于的几个月里我至少遇到了2次Solr的百科页面不能访问，而且是在工作日，我当时只是在查阅一个很小的配置问题。

　　做的最好的网站是Perl 和她的CPAN 模块。 每个模块的文档都可以很容易的在search.cpan.org 和 metacpan.org找到。 为了离线的需要，每个模块的文档都嵌入在源码本身里面， 当你安装这个模块到你的操作系统时，文档会自动的加载到你的本地帮助文档里面。 用户也可以使用：

　　得到文档。 由你来选择在线还是离线。

　　4. 没有提供随包安装文档

　　这个问题通常是软件包创建者的败笔，而不是项目作者的。比如，Ubuntu Linux中，Perl语言的文档是分离于语言本身软件包的可选软件包。用户必须知道她得显式地安装文档，就像安装核心包一样，否则当她需要文档时就没了。这种做法换取了几兆字节的硬盘空间，却牺牲了文档随时在手边的便利，对每个人都用处不大。

　　5. 缺少屏幕截图

　　截图能更好的抓住潜在用户的注意，描绘出一个合适的使用方式。 一图胜千言。对于互联网来说这点更重要，因为你都不能让用户可能读到一百个字。

　　截图对于让用户持续不断理解你的介绍是无价的，用户会根据的截图来做正确的事情。 一个截图能够让帮助用户判断他的结果和文档里面的截图是否正确。

　　很多优秀的项目在网站上用视频来介绍这个项目，这种情况正变得越来越普遍。更深入的视频介绍复杂的步骤。举个例子来说，Plone有个专门的网站来介绍他们的项目。不管怎么样，视频都取代不了截图。如果一个用户只是为了快速的了解一些你的界面，他是不愿意观看整个视频的。视频不能够被google的图片搜索搜索到，而截图却可以。

　　6.缺少实战例子

　　对于基于代码的项目来说，将项目运用到实战中的一些例子和截图一样也是有益处的。这些来自真实环境中的例子不是抽象的，而不是一些几乎是一次性的充满了演示名称的例子。我们需要做的是花费些时间来做一些例子，这些例子能展现用户使用软件怎么样解决实际项目中的问题。

　　我们以前经常在数学课中使用问题解决的教学方式，这种方式能够有效的应用在我们所教的内容中。

　　以前，我写过一个web机器人模块，并且想要解释下面的_link方法，可能会像下面一样展现这个方法的定义：

　　但是，如果我通过将它运用在实际例子中，它将变的多么易懂啊!

　　#点击第二个超链接会链接到字符串"download"

　　通过这个例子，上例中抽象的占位符变量名$regex_object和$link_index在学习者的脑海中将有相同的含义。

　　当然，你的实际例子不应该像上述例子中仅有两小段。正如Apache 项目的Rich Bowen说的，“一个正确的，体现功能的，可测验的，可评价的例子将胜过一页的项目功能赘述”。

　　不管怎么说，尽你所能，空间什么的都是浮云，专门为例子制作一份专门的文档，甚至哪怕是一本书，可以从用户那儿征集实际代码，并将它们中的最好例子展现出来。

　　7. 缺少足够的链接和参考

　　在文档中使用超链接。

　　不要以为一些东西在文档里面被说明了，就认为读者已经读了那部分文档了，或者甚至以为读者知道在哪里。比如你代码中有一段涉及到操作frobbitz对象，那你就有必要在第一次使用术语 frobbitz对象的时候，解释一下什么是frobbitz对象，或者链接到说明文档的相关章节。最好是上面两个都做。

　　8. 忽略了新的用户

　　从软件的作者自己的角度来看，写文档是件很简单的事情。而新的用户需要介绍性的文档，来使他们逐渐适应。

　　介绍应该是文档的一个单独的页面，理想的情况是应该有入门的例程，使得新用户能够很简单的成功使用软件。当你成功使用一个软件做很酷的事情时候，想想当时的兴奋感。让你的新用户也感受一下。

　　例如，一个图形开发包应该展示一系列的截图，来教用户如何添加数据到一个文件中，调用绘图程序，然后显示图片。一个代码库应该有调用代码库来显示输出的例子等等。 这些例子一定要简单，让用户很容易成功。而文档也应该在合适的地方介绍术语，并且链接到文档的术语解释部分。

　　一个单独的介绍文档可以让用户对软件有一个快速的理解。同时也能让介绍性文档不会出现在软件文档的主要部分。

　　9. 不去聆听用户的呼声

　　项目的所有者必须倾听该文档的用户。至少，听取那些积极使用你的软件的人的呼声。当用户花时间来给你发电邮，例如：“如果有一些解释或者链接来指导俺如何安装数据库驱动来安装这个程序就好了。”的话，请务必要认真对待。对于每一个发电邮向你报告种种问题的用户，你当然可以发梦般地回复说，其他人都不报告这个问题。但就算这么想，问题还是摆在那里。

　　然而，不仅要倾听用户的问题，发现问题背后的原因同样重要。如果有人经常在进行大容量数据库的更新时毛病重重，那他首先要在常见问题解答上(FAQs，别告诉我你没有这个东东)去查找解决方案。但是，这有可能是因为数据库更新的部分写得并不清楚，也有可能该概述文档并没有明显地指出这个部分。就这样，你的用户将永远不会去阅读问题解答手册的剩余部分。

　　此外帮助更多的人了解你的项目是多么的实用，这也为减少了一部分现有社区的麻烦。如果人们在你的邮件，论坛，以及IRC频道全是问的一些非常简单(或者也差不多很简单)的问题，很多人都会懒得回答。要知道到这些都是经常被问到的问题，并把它们的答案细分到每一点，这样人们就可以集中解决有趣的问题。

　　同时也要留意用户论坛之外的问题，经常去像StackOverflow一样的网站瞧瞧，为你的项目创建Google Alert，这样你就可以时刻知道关于你的项目在网络上讨论些什么内容。

　　10.不接受用户输入

　　如果你的项目有足够大的用户群，那么把用户的注释写入文档一般来说是很有意义的。我见过这样做的最好的例子是PHP。文档的每一页都允许授权的用户将注释添加到页面，以帮助阐述关键点，或添加核心文档中没有的例子。当然，PHP团队也让读者自己可以选择显示或者隐藏用户评论。

　　这样做的好处很多，但同时也需要注意维护。随着时间的推移，一些注释应该被淘汰掉，以防止过度生长。例如，PHP文档页面中关于如何在命令行中调用PHP代码的用户注释有43个，可以追溯到2001年。这些注释使核心文件显的很臃肿。所以这些注释应当归档或消除掉，把最重要几点纳入到核心文件中。

　　使用Wiki是一个很好的方法。但是，如果你的wiki不允许用户下载所有页面打包在一起(见上述第3项)，那么你的用户将受到承载项目的互联网连接和Web服务器的摆布而无能为力。

　　11. 除了安装这个软件，没法知道它能做什么

　　每个软件项目至少需要一个功能列表和一页截图，让好奇的潜在用户知道为什么他要试试这个软件。对于那些找安装包来安装软件的用户来说，这样可以使他更容易地了解到这个软件值得他花时间下载和安装的理由。

　　要做到这一点，图片是一个极好的方案。你的项目应该有一个专门的“屏幕截图”页面来展示使用这个工具的真实例子(请参阅前文第五项)。如果这个项目是像一个图书馆一样纯粹的代码，那么就应该有一个示范页面来展示使用这个工程的代码。

　　12. 依赖技术手段来编写文档

　　软件作者经常使用自动化文档系统来生成文档。但是忘记了有些部分是需要自己写的。 自动化系统可以让事件变得容易维护，但是无法完全代替手动编写。

　　这糟糕示例莫过于这个除了从版本控制系统中生成的一堆提交信息之外什么都没有写的更新日志了,没有一个总结性的简介来说明。更新日志应该列举出：新特性、bug修复、和潜在的不兼容，它的目标读者是最终的用户。提交日志是给项目的开发者看的;很简单就可以生成，但是并不是用户所需要的。

　　看一下这个来自Solarium文档的页面(Solarium：Solr搜索引擎的PHP接口) 。首先，顶部的声明占了半屏，但是没有给用户任何信息。其次，除了一个函数名列表外没有任何解释性的描述了。 "METHOD_FC"枚举的意思是"Facet method fc"。但是，FC是什么? 没有关于facet方法不同的说明，也没有给用户查询的链接。这个自动生成的页面看起来很漂亮，可能感觉也像是文档，但是它们真不是。

　　13. 鄙视用户

　　类似“RTFM(Read the Freaking Manual)”这样的态度会伤害你的项目和你的文档。

　　认为用户不懂如何使用你的项目是用户的错，这种态度十分嚣张。没有了解就进行“他们都懒得看文档”这种道德谴责更糟糕。我们中的大多数人都从经作为用户遭遇过这种态度。己所不欲，勿施于人。

　　即使用户的问题能够在文档中找到解决方法，认为这是用户错误的想法也是不当的。 也许是你的文档写的太烂了或是排版不好。 也许你应该提高“入门”部分(见#8)，更好的解释软件的用处。 也许某些信息需要在文档的不同部分重复出现多次。 也许缺少用户如何找到那些小知识点的指引。

　　你要知道，新用户对你的项目一无所知。所以你项目的文档团队应当确保无知是可以治愈的。

　　总结

　　我相信，你曾经历过很多类似的问题，我只是希望，我的文档能有所帮助。如果你有什么问题，可以回复告之我们。我并不是针对某个项目指手画脚，要知道，每个开源项目的问题各不相同。

　　最重要的是，我希望你能够认识到你所参与的项目文档中所存在的问题，并采取行动改善它们。幸运的是，改进文档能够更好的将新人带入项目中。经常有人问我：“我应该如何参与开源项目?”我的建议就是改进文档。

　　尽可能让贡献者，无论新手老手，更容易知道文档中的哪部分需要帮助。创建一个任务列表，比如在你的 BUG 跟踪系统中，说明那些需要帮助。尽可能具体的说明你的需求。不要仅仅说：“我们需要更多的示例。”创建具体的任务，例如：“添加如何进行任务 X 的示例代码”，“添加报表生成器的屏幕截图”或是“在 README文件中添加依赖信息”。贡献者想要帮忙，但往往不知道从何处入手。

　　文件并不是开源项目中最吸引人的部分，对于我们大多数人来说，它并不能带来乐趣，但若是没有一份好文档，用户无法更好的获得服务，而你的项目也将遭受影响。