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

10顶
0踩

2013-01-11 17:52 by 副主编 wangguo 评论(7) 有12605人浏览

开源文档

声明：ITeye资讯文章的版权属于ITeye网站所有，严禁任何网站转载本文，否则必将追究法律责任！

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

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

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.org和metacpan.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手册）”的态度，这可能会吓走一批潜在的用户。

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

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