人们讨厌你开源文档的13个原因

大多数程序员都非常在乎他们开发的软件的质量，但是他们却很少关注相应的文档。虽然很少有人提及这一点，但是一份好的文档确实能为你的软件的成功插上翅膀。没有好文档，大家不会用你的东西，没有好文档，大家很难喜欢你的东西。如果你能成功创造良好的用户体验，你那些高兴的用户们就会口口相传的为你的软件进行宣传——只有他们真正理解你的工作，他们才可以做到这一点——这就更不能没有一份好的文档了。

1.缺少一个优秀的简介

3.只有在线文档
 
与前一点相反，只有在线文档也是不好的。有些项目在完成时并没有同步打包放出符合规范的文档。

4. 没有提供随包安装文档

5. 缺少屏幕截图

6.缺少实战例子

7. 缺少足够的链接和参考

9. 不去聆听用户的呼声

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

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

总结 
　　
我相信，你曾经历过很多类似的问题，我只是希望，我的文档能有所帮助。如果你有什么问题，可以回复告之我们。我并不是针对某个项目指手画脚，要知道，每个开源项目的问题各不相同。
　　
最重要的是，我希望你能够认识到你所参与的项目文档中所存在的问题，并采取行动改善它们。幸运的是，改进文档能够更好的将新人带入项目中。经常有人问我：“我应该如何参与开源项目的建议就是改进文档。 
  
尽可能让贡献者，无论新手老手，更容易知道文档中的哪部分需要帮助。创建一个任务列表，比如在你的 BUG 跟踪系统中，说明那些需要帮助。尽可能具体的说明你的需求。不要仅仅说：“我们需要更多的示例。”创建具体的任务，例如：“添加如何进行任务 X 的示例代码”，“添加 表生成器的屏幕截图”或是“在 README文件中添加依赖信息”。贡献者想要帮忙，但往往不知道从何处入手。 
　

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