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