开源 英文原文：13 Things People Hate about Your Open Source Docs

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

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

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

1.缺少一个优秀的简介

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

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

• 这个软件是干啥的
• 目标用户是谁
• 运行平台和硬件
• 依赖关系
• 如何安装

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

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

其它翻译版本 (1) 加载中

2. 没有在线文档

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

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

其它翻译版本 (1) 加载中

3.只有在线文档

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

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

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

其它翻译版本 (1) 加载中

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

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

perldoc Module::Name

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

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

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

5. 缺少屏幕截图

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

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

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

6.缺少实战例子

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

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

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

 $mech->follow_link( text_regex => $regex_object, n => $link_index );

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

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

$mech->follow_link( text_regex => qr/download/, n => 2 );

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

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

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

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

在文档中使用超链接

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

8. 忽略了新的用户

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

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

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

一个单独的介绍文档可以让用户对软件有一个快速的理解。同时也能让介绍性文档不会出现在软件文档的主要部分。 本文中的所有译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接。 2KB翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

2KB项目（www.2kb.com，源码交易平台）,提供担保交易、源码交易、虚拟商品、在家创业、在线创业、任务交易、网站设计、软件设计、网络兼职、站长交易、域名交易、链接买卖、网站交易、广告买卖、站长培训、建站美工等服务