8. 忽略了新的用户

　　从软件的作者自己的角度来看，写文档是件很简单的事情。而新的用户需要介绍性的文档，来使他们逐渐适应。

　　介绍应该是文档的一个单独的页面，理想的情况是应该有入门的例程，使得新用户能够很简单的成功使用软件。当你成功使用一个软件做很酷的事情时候，想想当时的兴奋感。让你的新用户也感受一下。

　　例如，一个图形开发包应该展示一系列的截图，来教用户如何添加数据到一个文件中，调用绘图程序，然后显示图片。一个代码库应该有调用代码库来显示输出的例子等等。 这些例子一定要简单，让用户很容易成功。而文档也应该在合适的地方介绍术语，并且链接到文档的术语解释部分。

　　一个单独的介绍文档可以让用户对软件有一个快速的理解。同时也能让介绍性文档不会出现在软件文档的主要部分。

　　9. 不去聆听用户的呼声

　　项目的所有者必须倾听该文档的用户。至少，听取那些积极使用你的软件的人的呼声。当用户花时间来给你发电邮，例如：“如果有一些解释或者链接来指导俺如何安装数据库驱动来安装这个程序就好了。”的话，请务必要认真对待。对于每一个发电邮向你报告种种问题的用户，你当然可以发梦般地回复说，其他人都不报告这个问题。但就算这么想，问题还是摆在那里。

　　然而，不仅要倾听用户的问题，发现问题背后的原因同样重要。如果有人经常在进行大容量数据库的更新时毛病重重，那他首先要在常见问题解答上(FAQs，别告诉我你没有这个东东)去查找解决方案。但是，这有可能是因为数据库更新的部分写得并不清楚，也有可能该概述文档并没有明显地指出这个部分。就这样，你的用户将永远不会去阅读问题解答手册的剩余部分。

　　此外帮助更多的人了解你的项目是多么的实用，这也为减少了一部分现有社区的麻烦。如果人们在你的邮件，论坛，以及IRC频道全是问的一些非常简单(或者也差不多很简单)的问题，很多人都会懒得回答。要知道到这些都是经常被问到的问题，并把它们的答案细分到每一点，这样人们就可以集中解决有趣的问题。

　　同时也要留意用户论坛之外的问题，经常去像StackOverflow一样的网站瞧瞧，为你的项目创建Google Alert，这样你就可以时刻知道关于你的项目在网络上讨论些什么内容。

　　10.不接受用户输入

　　如果你的项目有足够大的用户群，那么把用户的注释写入文档一般来说是很有意义的。我见过这样做的最好的例子是PHP。文档的每一页都允许授权的用户将注释添加到页面，以帮助阐述关键点，或添加核心文档中没有的例子。当然，PHP团队也让读者自己可以选择显示或者隐藏用户评论。

　　这样做的好处很多，但同时也需要注意维护。随着时间的推移，一些注释应该被淘汰掉，以防止过度生长。例如，PHP文档页面中关于如何在命令行中调用PHP代码的用户注释有43个，可以追溯到2001年。这些注释使核心文件显的很臃肿。所以这些注释应当归档或消除掉，把最重要几点纳入到核心文件中。

　　使用Wiki是一个很好的方法。但是，如果你的wiki不允许用户下载所有页面打包在一起(见上述第3项)，那么你的用户将受到承载项目的互联网连接和Web服务器的摆布而无能为力。

　　11. 除了安装这个软件，没法知道它能做什么

　　每个软件项目至少需要一个功能列表和一页截图，让好奇的潜在用户知道为什么他要试试这个软件。对于那些找安装包来安装软件的用户来说，这样可以使他更容易地了解到这个软件值得他花时间下载和安装的理由。

　　要做到这一点，图片是一个极好的方案。你的项目应该有一个专门的“屏幕截图”页面来展示使用这个工具的真实例子(请参阅前文第五项)。如果这个项目是像一个图书馆一样纯粹的代码，那么就应该有一个示范页面来展示使用这个工程的代码。

　　12. 依赖技术手段来编写文档

　　软件作者经常使用自动化文档系统来生成文档。但是忘记了有些部分是需要自己写的。 自动化系统可以让事件变得容易维护，但是无法完全代替手动编写。

　　这糟糕示例莫过于这个除了从版本控制系统中生成的一堆提交信息之外什么都没有写的更新日志了,没有一个总结性的简介来说明。更新日志应该列举出：新特性、bug修复、和潜在的不兼容，它的目标读者是最终的用户。提交日志是给项目的开发者看的;很简单就可以生成，但是并不是用户所需要的。

　　看一下这个来自Solarium文档的页面(Solarium：Solr搜索引擎的PHP接口) 。首先，顶部的声明占了半屏，但是没有给用户任何信息。其次，除了一个函数名列表外没有任何解释性的描述了。 "METHOD_FC"枚举的意思是"Facet method fc"。但是，FC是什么? 没有关于facet方法不同的说明，也没有给用户查询的链接。这个自动生成的页面看起来很漂亮，可能感觉也像是文档，但是它们真不是。

　　13. 鄙视用户

　　类似“RTFM(Read the Freaking Manual)”这样的态度会伤害你的项目和你的文档。

　　认为用户不懂如何使用你的项目是用户的错，这种态度十分嚣张。没有了解就进行“他们都懒得看文档”这种道德谴责更糟糕。我们中的大多数人都从经作为用户遭遇过这种态度。己所不欲，勿施于人。

　　即使用户的问题能够在文档中找到解决方法，认为这是用户错误的想法也是不当的。 也许是你的文档写的太烂了或是排版不好。 也许你应该提高“入门”部分(见#8)，更好的解释软件的用处。 也许某些信息需要在文档的不同部分重复出现多次。 也许缺少用户如何找到那些小知识点的指引。

　　你要知道，新用户对你的项目一无所知。所以你项目的文档团队应当确保无知是可以治愈的。

　　总结

　　我相信，你曾经历过很多类似的问题，我只是希望，我的文档能有所帮助。如果你有什么问题，可以回复告之我们。我并不是针对某个项目指手画脚，要知道，每个开源项目的问题各不相同。

　　最重要的是，我希望你能够认识到你所参与的项目文档中所存在的问题，并采取行动改善它们。幸运的是，改进文档能够更好的将新人带入项目中。经常有人问我：“我应该如何参与开源项目?”我的建议就是改进文档。

　　尽可能让贡献者，无论新手老手，更容易知道文档中的哪部分需要帮助。创建一个任务列表，比如在你的 BUG 跟踪系统中，说明那些需要帮助。尽可能具体的说明你的需求。不要仅仅说：“我们需要更多的示例。”创建具体的任务，例如：“添加如何进行任务 X 的示例代码”，“添加报表生成器的屏幕截图”或是“在 README文件中添加依赖信息”。贡献者想要帮忙，但往往不知道从何处入手。

　　文件并不是开源项目中最吸引人的部分，对于我们大多数人来说，它并不能带来乐趣，但若是没有一份好文档，用户无法更好的获得服务，而你的项目也将遭受影响。