大多数开源开发人员喜欢考虑他们构建的软件的质量，但他们的文档质量往往被遗忘。没有人谈论一个项目的文档有多好，但是文档对一个项目的成功有直接的影响。没有一个好的文档，用户可能根本不会使用你的项目，或者他们可能根本不喜欢它。然而，大多数开源项目的文档却极其令人失望，主要表现在以下几个方面。1.缺乏好的自述文件或介绍自述文件是潜在用户对您的项目的第一印象。如果项目在GitHub上，readme会自动显示在项目主页上。如果您不小心弄错了自述文件，那些潜在用户可能永远不会回来。所以你的项目一定要有一个好的readme来吸引用户来你的项目。自述文件至少应包括以下内容：项目是为什么样的用户运行的在什么硬件或平台上主要依赖项如何安装或深入指导这些是为从未听说过您的项目的人编写的甚至在可能永远不会考虑您的项目的用户之前。当然，不要以为每个阅读你的自我报告的用户都知道它是什么。如果有必要，您需要做一些注释并附上一些有用的链接，以方便用户了解您的项目。2.不提供在线文档虽然我没有看到这方面的研究调查，但我认为90%的文档都是通过谷歌或其他浏览器在互联网上找到的。因此文档必须在线且可用。我是怎么发现这个的？因为很多用户经常直接从网上搜索问题的答案，而没有看常见问题的答案，这样往往会导致项目出现问题。因此，提供在线文档可以帮助用户更好地解决问题。3.只提供在线文档问题的另一面是开发商只提供在线文档。某些项目不附带该项目可以与之交互的文档，或者包含文档的不合规版本。例如，PHP语言没有任何文档，如果您需要文档，您必须使用单独的页面打开它们。然而，更糟糕的是，只能下载核心代码。结果，用户可能无法获得对他们自己有用的信息。开源项目不能想当然地认为用户在访问Internet时需要在线文档。当然，你也不希望用户过于依赖你的项目网站。4.不包含安装文档这个问题通常是包的创建者的问题，而不是项目开发者的问题。例如，在UbuntuLinux操作系统中，用于Perl语言选择的软件包本身是一个单独的文件。用户在安装时一定要知道自己需要的安装文件和核心语言文件，以便用户在遇到问题时能够及时解决问题。5.缺少截图有没有更好的方式来吸引潜在用户的注意力，或者说明软件的正确使用方法？更聪明的做法是截屏。在网络时代，一张图片可能胜过千言万语。截图可以让用户判断自己使用的方法是否正确，也很容易让他找到自己错在哪里。因此，必要的截图对于开源文档也是至关重要的。6.缺乏例子对于代码类的项目，模拟的截图当然很好，但是相关的例子也是必不可少的。这些实例不应该是抽象的，而是来自现实世界。花时间创建一些与项目相关的示例，向用户展示如何解决在使用该软件时出现的问题。7.链接和引用不足如果有超链接，记得在文档中使用。不要以为用户看了文档就可以理解和理解。文档中可能有一些用户无法理解的内容。这时候，你需要用你所有的超链接和引用来帮助用户解决一些问题。8.忘记新用户。当您编写文档时，您是从开发人员本身的角度来编写的。这对软件开发人员来说非常容易。但是，对于那些新用户，需要入门文档。为了让新用户尽早了解你的软件或者熟练掌握软件的使用方法，我觉得应该单独用一个页面来写给用户的介绍文档。9.不倾听用户需求项目开发人员必须倾听用户对整个项目的需求。最有效的方法是让更多的人尝试你的项目，找出问题所在。同样重要的是，在倾听用户需求的过程中，项目开发者应该考虑用户提出这些问题背后的真正原因。10.不接受用户输入如果你的项目有足够大的用户群，你可以让用户直接在文档中添加评论。我见过的最好的例子是PHP语言，它的文档中的每一页都允许经过身份验证的用户添加评论，或者添加不属于核心文档的评论。原文来自：http://www.evget.com/article/2014/11/5/21786.html
