开源项目文档应规避的13处“硬伤”

转载 2015年08月21日 17:10:44
大多数开源项目开发者只关注于软件的质量,而常常忘记编写高品质的文档。但是,文档的好坏对于一个项目的成功有着至关重要的作用,它可以帮助用户快速了解这个项目,或在用户的使用过程中提供一些帮助。 

然而,有很多开源项目的文档令人失望,主要表现在以下几个方面。 

1.  缺乏一个良好的README或介绍 

README可以使潜在用户对你的项目有一个初步、快速的了解,如果该项目在GitHub上,README文件会自动显示在该项目的主页。如果你想一下子吸引住用户,并让他们继续探索你的项目,那么一个好的介绍必不可少。如果介绍很糟糕,这些用户可能不会再回来了。 

README文件至少应该包含: 

  • 项目用途
  • 针对人群
  • 运行的平台或硬件
  • 重要依赖
  • 如何安装,或更深层次的东西
项目README必须要针对那些从来没听说过你的项目的人来写。比如,项目中有一个计算Levenshtein距离的模块,你不要想当然地认为每个正在读README的人都知道Levenshtein是什么东西。你应该说明一下,并加上相关详细信息的链接,便于人们进一步探索。 

在介绍一个新东西时,不要再引入其他的新东西,比如“NumberDoodle类似于BongoCalc,但更好”,人们或许压根不知道BongoCalc。 

2.  没有在线提供文档 

项目的文档必须能够在谷歌中查找到,因此,要确保你的文档在线可用。 

我之前发布了一个开源项目,令我恼火的是,用户经常给我发邮件问一些我已经在FAQ中回答过的问题,后来我才发现,我没有将FAQ放在网站上。这是一个比较容易犯的错误,因为作者没有站在用户的角度考虑问题。 

3.  只提供在线文档 

你不能不提供在线文档,但同时也不能只提供在线文档。有些项目最终版本中没有附上文档,或者包含了项目开发阶段的不完整的文档,而将最终文档放在网上,这给无网络的用户,造成了一定的困扰。 

比如,Solr项目,有一个非常全面的Wiki(文档),但是提供下载的却是一个2200页的自动生成的API Javadocs,其中针对最终用户的唯一的文档是一个单页的教程。 

PHP语言包也没有附带任何文档,如果你想要文档,你必须到一个单独的页面。糟糕的是,只提供下载核心文档,并且还没有对用户有帮助的注释。 

开源项目不能想当然地认为用户都能上网。你也不能让用户过分依赖于项目网站。在过去几个月中,我已经发现Solr wiki宕机至少两次了,而我当时正急需解决一个棘手的配置问题。 

这一方面做的比较好的是Perl和其CPAN模块库。每个模块文档都以一种易于阅读的超链接格式提供在search.cpan.orgmetacpan.org上。对于离线环境,每个模块文档嵌入在代码本身上,当用户安装模块时,会自动创建本地文档作为说明手册。用户也可以在Shell中使用perldoc Module::Name命令来获取文档。无论是在线或是离线,你都可以使用。 

4.  文档没有自动安装 

这通常是安装包创建者的错。比如,在Ubuntu Linux中,Perl语言的文档时一个独立的、可选的包,用户在安装时可能会遗漏掉这个选项。尽管节省了几MB的磁盘空间,但用户在需要时无法及时找到。 

5.  缺少截图 



有时候,一张图片胜过千言万语。 

一个屏幕截图,可以帮助用户直观地比较操作结果,看是否正确地完成了各项任务,或轻松地找出哪里出现了问题。 

现在,使用视频来介绍项目也变得普遍,视频可以显示一个复杂过程的步骤。比如Plone项目,有一个专门网站来提供视频教程。但是,视频还无法取代屏幕截图,因为用户无法通过视频快速找到某些内容(需要一点一点看),且视频无法被谷歌图片搜索收录,屏幕截图可以。 

6.  缺乏现实例子 

对于基于代码的项目,截图固然不错,但给出一个实例更实用。这些例子不应该是抽象的,而是来自现实世界中的。开发者应该花时间创建一个相关的例子,来向用户展示该项目是如何解决问题的。 

正如Apache项目的Rich Bowen所说,“一个正确的、功能齐全的、经过测试的、有注释的例子,胜过一页的乏味介绍。” 

7.  缺少链接和参考 

不要认为你要解释的内容是文档的一部分,或者用户已经在前面读过,或者知道它们在哪里,就无需再使用超链接。比如,你的项目中有一部分代码作用是操作frobbitz对象,你有必要解释一下frobbitz对象,或链接到相关页面。 

8.  不考虑新用户 

编写文档的时候,不要认为一些用户已经知道一些东西而不去详细介绍。你应该考虑到新用户,并用一个单独的页面、最好的例子,来让新用户快速了解你的项目。 

9.  不听用户的反馈 



你应该积极听取使用你软件的用户的建议和需求,比如“如果有一个关于数据库驱动程序安装的介绍或链接就好了,这将帮助我安装这个程序”。 

根据用户的反馈,创建一个常见问题。并经常关注其他一些网站或论坛,如StackOverflow,并创建一个Google Alert,来了解互联网上针对你的项目的讨论。 

10.  不接受用户输入 

如果你的项目有足够大的用户群,那么你可以考虑让用户能够直接将意见写到文档中。我见过最好的例子是PHP,每一页文档都允许经过身份验证的用户在页面中进行注释,或添加非核心文档例子。 

这些内容需要维护,因为随着时间的推移,会出现一些过时的注释,这些需要被淘汰。 

11.  必须安装后才能了解项目的用途 

每个软件项目都需要有一个功能列表和页面截图,如果是纯粹的代码项目,比如一个库,也应该有一个示例页面。 

12.  依赖于文档自动生成 

大多时候,软件开发者会使用自动化的文档生成系统,来代替自己的工作。他们忘记了还需要手动写其他部分。

最坏的情况是,changelog中除了一些提交信息外没有任何内容。changelog应该列出新的功能、错误修复以及潜在的兼容性问题,它的目标群体是最终用户。而提交日志是给开发者看的。 

13.  以傲慢的态度对待小白用户 

不要对用户的问题都报以“RTFM(Read the Freaking Manual,去读那些TMD手册)”的态度,这可能会吓走一批潜在的用户。 

如果用户的问题可以在文档中找到,但他们没有这样做,不要认为这是愚蠢的。有可能是因为你的文档写得糟糕,难以阅读,或者不完整。你需要耐心地改善“入门”章节,说明软件的目的是什么,或者给用户指明在哪里可以找到相关的信息。 

从《UML的三大硬伤》说起

这是Liu Junsong朋友给CSDN的来信,我转贴在此----------------------------------------------最近,在>杂志上发表了高展先生的一篇文章"UML的...
  • gigix
  • gigix
  • 2002-05-28 13:29:00
  • 2737

情商低是硬伤

这两天陪关页培逛南京,是用我的慢节奏带着她逛的,挺开心的。对南京的印象更好了。 这几天和她说了很多话,仿佛把心里面所有的话像倒水似的叽噜咕噜地倒了出来,其中包括一些从来没和别人说过的话。平常话不多、总...
  • keroro520
  • keroro520
  • 2014-01-08 18:06:54
  • 944

《UML三大硬伤》的16条硬伤

除了Think在“谁的硬伤”一文中列举之外,Dr. OO又列举出了“三大硬伤”一文的16条错误。我代他转贴到CSDN。  1) “图 3是采用UML的Use Case 图来描述组织结构,它只能描述到岗...
  • gigix
  • gigix
  • 2002-05-23 17:39:00
  • 2205

web前端开发笔试集锦(javascript篇1)转

原文出处: http://hi.baidu.com/jinhui04/item/eaf40034fa00def597f88dbc 1, 判断字符串是否是这样组成的,第一个必须是字母,后面可以是字...
  • chelen_jak
  • chelen_jak
  • 2014-02-14 15:38:38
  • 1609

数理逻辑习题集(9)

这10道题中,有些是在是太古怪了,行测中的数列了,组合数学的题目了,还有条件随机场等等。 1.根据下列数字规律,应填入括号处的数字是( )。 3,0,6,6,18,( ) A.24 ...
  • qq_35082030
  • qq_35082030
  • 2017-12-21 20:55:04
  • 335

分支-08. 高速公路超速处罚(15)

按照规定,在高速公路上行使的机动车,超出本车道限速的10%则处200元罚款;若超出50%,就要吊销驾驶证。请编写程序根据车速和限速自动判别对该机动车的处理。 输入格式: 输入在一行中给出2...
  • oFengWuYu1
  • oFengWuYu1
  • 2014-05-25 10:28:59
  • 2179

算法是硬伤,求助.............

比如说有一个list数组,数组大小不确定。 list list 如何将list   按照日期         分成n个list?...
  • yiqi7859
  • yiqi7859
  • 2017-01-08 17:55:15
  • 74

ERP产品缺陷

国内ERP产品的缺陷一直是企业及软件供应商所关注的焦点,国内ERP市场起步较晚,相对其它国外的ERP软件,无论在业务流程还是稳定性方面,我们做的都不够理想,不可否认,国内ERP产品在质量上确实存在很多...
  • licheng6302
  • licheng6302
  • 2012-02-15 22:33:33
  • 3080

介绍一些java开源项目

ZBNO 中文自动断词引擎开源项目简介:英文句子里的词汇都有空格分开,中文句子里的词却没有这个特点。如何识别中文词语便成了中文信息检索的关键技术之一。ZBNO在此公布我们的《中文自动断词引擎开源项目》...
  • dongle2001
  • dongle2001
  • 2005-10-16 20:09:00
  • 835

程序员高手和菜鸟究竟差在哪里?

随着做软件的时间越来越长,我发现,做软件越来越难。难在哪?难在怎么做出一个好的软件。好的软件标准是什么?两个词,好用,好看!程序员的最大价值在于做出好用又好看的软件的能力。因此,我觉得程序员的价值绝对...
  • UW63ZqpKxwlRL1
  • UW63ZqpKxwlRL1
  • 2018-01-13 00:00:00
  • 661
收藏助手
不良信息举报
您举报文章:开源项目文档应规避的13处“硬伤”
举报原因:
原因补充:

(最多只允许输入30个字)