关于开源文档：程序员可能忽略的十件事

via: http://code.csdn.net/news/2822503

 

大多数开源开发人员喜欢思考他们构建软件的质量，但其文档的质量常常被遗忘。没有人谈论一个项目的文档是多么出色，但其实文档对一个项目的成功却有直接的影响。没有一个良好的文档可能用户根本不会使用你的项目，亦或者压根不会喜欢。

然而大多数开源项目的文档都是令人极其失望的，主要从以下的几个方面来体现。

 

1. 缺乏一个好的自述或介绍

自述是潜在用户对你项目的第一印象。如果项目在 GitHub 上，自述自动的显示在该项目的主页上。如果你稍微不留神将自述弄错了，这些潜在的用户有可能再也不会回来了。所以你的项目必须有一个好的自述来吸引用户对你的项目产生兴趣。

 

自述文件至少应该包括以下几点说明：

是什么项目

面向何种用户

运行在什么硬件或者平台上

主要依赖关系

如何安装或者深入的方向指针

这些都是写给那些之前从未听说过你的项目甚至可能永远不会考虑你的项目的用户。当然也不要以为每个阅读你自述的用户都知道那是什么，必要的时候需要做出一些注解以及附上一些有用的链接，方便用户了解你的项目。

 

2. 不提供在线文档

虽然没有看到过关于这方面的研究调查，但我想 90% 的文档都是通过谷歌或者互联网的其他浏览器来查找的。所以文档必须在线并且可用。这一点我是如何发现的呢？因为很多的用户常常会不看常见问题的解答，而直接从网上搜索问题的答案，这常常就会在项目中出现问题。因此提供在线的文档可以帮助用户更好的解决问题。

 

3. 只有在线文档

这个问题的另一面就是开发人员只提供在线的文档。有些项目不附带该项目可交互的文档，或者包含的文档是不符合的版本。例如 PHP 语言不附带任何文档，如果你想要文档，必须用一个单独的页面来打开他们。然而更糟糕的是，只有核心代码可以下载。这样导致用户可能不能获得对自己有用的信息。

开源项目不能想当然的认为用户访问互联网时他们需要在线的文档。当然你也不希望用户过分的依赖你的项目网站。

 

4. 不包含安装文档

这个问题通常是包的创造者而不是项目开发者的问题。例如在 Ubuntu Linux 操作系统中，Perl 语言选择的包本身是一个单独的文档。用户必须知道他在安装的时候所需要的安装文档以及核心语言的文档，这样方便用户在遇见问题时及时地解决。

 

5. 缺乏截图

有没有更好的方式来获取潜在用户的注意，或者说明软件的正确使用方法？比较明智的做法是截图。在互联网时代，一张图也许胜过千言万语。截图能让用户判断自己使用的方法是否正确，也容易让他找到自己出错的地方。因此必要的截图对于开源文档来讲也是至关重要的。

 

6. 缺乏实例

对于基于代码的项目，模拟的截图固然是非常不错的，但是相关的实例也是必不可少的。这些实例不应该是抽象的，而应该是从现实世界当中提取的。花时间创建一些与项目相关的实例，向用户展示如何解决软件使用过程中出现的问题。

 

7. 不充分的链接和引用

如果有超链接，记得在文档中使用它们。不要以为用户读完文档就能明白并且理解，文档当中可能会存在一部分用户并不能理解的东西。这时候就需要你使用你所有的超链接以及引用来帮助用户解决一些问题。

 

8. 忘记新用户

当你写文档时，你是站在开发者自己的角度上来编写的，这对于软件的开发者来说着很容易。然而对于那些新用户来讲，则需要入门文档。为了使新用户能够尽早的了解你的软件或者说熟练掌握使用软件的方法，我认为应该使用单独的页面来为用户书写入门文档。

 

9. 不倾听用户需求

项目的开发者必须倾听用户对整个项目的需求。最有效的方法就是让更多的人对你的项目进行试用来找出问题。同等重要的是，在倾听用户需求的过程当中，项目开发人员应该考虑到用户提出这些问题背后的真正原因。

 

10. 不接受用户输入

如果你的项目有一个足够大的用户群，你可以让用户直接将评论添加到文档当中。我见过的最好的例子是 PHP 语言，其文档中的每个页面允许经过身份验证的用户添加评论，或添加的评论不属于核心文档。