【IT168 评论】大多数程序员都非常在乎他们开发的软件的质量，但是他们却很少关注相应的文档。虽然很少有人提及这一点，但是一份好的文档确实能为你的软件的成功插上翅膀。没有好文档，大家不会用你的东西，没有好文档，大家很难喜欢你的东西。如果你能成功创造良好的用户体验，你那些高兴的用户们就会口口相传的为你的软件进行宣传——只有他们真正理解你的工作，他们才可以做到这一点——这就更不能没有一份好的文档了。
可惜，大多数开源项目并没有好的文档。他们令人失望的原因有几个方面。
我下面给出的例子并不是经过权威认证的，我也没有挑错的意思。我只是认为以下这些我最近用过的软件中，他们的一些东西我并不是十分认同。你可以看看我从那些或许是你最喜欢的软件当中发现的问题(不管你是开发者还是用户)，然后如果可以，我希望你能得到一点启发。
1.缺少一个优秀的简介
软件的简介可以给你的潜在用户第一印象。特别是当这个软件放到GItHub上的时候，简介货自动被展示在软件的主页上。如果你简介搞的很糟糕，或许你的用户就一去不复返了。如果你想一下子抓住用户的眼球，然后诱导他们使用你的软件，写个优秀的简介吧。
简介永远都是要解释点东西，他至少应当包含如下几点：
• 这个软件是干啥的
• 目标用户是谁
• 运行平台和硬件
• 依赖关系
• 如何安装
以上这些必须考虑哪些从来没有听说过你的项目的人的技术水平，他们可能从来没有接触过你的软件所涉及的项目。如果你的模块是用来计算Levenshtein distance(译者注：它指的是一种常用的衡量两个字符串之间相似情况的度量。它是编辑距离的最为广泛使用的一种定义，大多数情况下编辑距离被用来特指Levenshtein距离。所谓字符串A和B的编辑距离就是指一个字符串A需要经过多少次编辑可以得到字符串B。)别指望你的用户在读你的简介之前就对levenshtein distance有一定的了解。你最好解释一下，然后给那些想要深入了解的用户几个链接。
不要在简介中涉及其他的项目，比如“我这个玩意儿类似于另一个东西，但是比他好多了!”。这对于连你所涉及的那个项目都没有挺熟过的人来说：没有用。
2. 没有在线文档
虽然我还没有看到关于这方面的研究，但是我敢保证90%的文档查阅工作都是通过Google和浏览器在互联网上完成的。 你的的项目必须要有在线的文档。说到这里，我感动惭愧的是，我自己的项目ack居然 没有在大多数人用来查找文档的地方。我的这个推断是基于我自己的使用情况，也就是说，如果我想知道一个命令怎么用，我会查看它的man(手册)页。
为什么这会引起我的注意呢?因为，总会有用户发邮件来问我已经在FAQ中回答过的问题，他们不阅读我的FAQ文档令我很烦恼。 原来，他们在网络上查找，但是我却没有将FAQ发布在网上。犯这样的错误很容易，因为我熟悉这个项目，因此实际上我自己并不 使用FAQ，因此我没有注意到它们没有在线版。很多问题都来自同样的疏忽：作者并没有换位思考。
