diff --git "a/\347\254\254\345\233\233\351\203\250\345\210\206\342\200\224\342\200\224\345\220\257\345\212\250\350\207\252\345\267\261\347\232\204\345\274\200\346\272\220\351\241\271\347\233\256/\345\274\200\346\272\220\351\241\271\347\233\256\347\232\204\347\273\264\346\212\244\345\222\214\347\256\241\347\220\206.md" "b/\347\254\254\345\233\233\351\203\250\345\210\206\342\200\224\342\200\224\345\220\257\345\212\250\350\207\252\345\267\261\347\232\204\345\274\200\346\272\220\351\241\271\347\233\256/\345\274\200\346\272\220\351\241\271\347\233\256\347\232\204\347\273\264\346\212\244\345\222\214\347\256\241\347\220\206.md" index 1eabaa72b4fbf8850daa47fe99c0e8318999b40e..8a8397120a3b8b371a85f603a680b22d4a4354c1 100644 --- "a/\347\254\254\345\233\233\351\203\250\345\210\206\342\200\224\342\200\224\345\220\257\345\212\250\350\207\252\345\267\261\347\232\204\345\274\200\346\272\220\351\241\271\347\233\256/\345\274\200\346\272\220\351\241\271\347\233\256\347\232\204\347\273\264\346\212\244\345\222\214\347\256\241\347\220\206.md" +++ "b/\347\254\254\345\233\233\351\203\250\345\210\206\342\200\224\342\200\224\345\220\257\345\212\250\350\207\252\345\267\261\347\232\204\345\274\200\346\272\220\351\241\271\347\233\256/\345\274\200\346\272\220\351\241\271\347\233\256\347\232\204\347\273\264\346\212\244\345\222\214\347\256\241\347\220\206.md" @@ -2,15 +2,19 @@ 「酒香也怕巷子深」这句话在互联网时代特别适用。我在 N 年前看过一本创业公司老板写的研发项目管理方面的书，到现在还记得一句话 「一个公司的核心竞争力，一是技术，二是营销」。对于一个开源项目，将代码放发布到代码托管平台仅仅是一个开始，真正重要的是社区运营工作。如何让更多的人能够快速了解你的项目而不是无人问津？如何让有兴趣的人更积极的参与项目而不是永远仅仅依靠一己之力不可持续？这些都是非常现实的挑战，也是一个开源项目能否健康发展的重要基础。 Apache 软件基金会（ASF）的 Apache Way 的核心理念就是 Community over Code （社区重于代码），也说明开源项目建立社区的重要性。 -要做好一个开源项目的推广，项目内容中除了源代码之外，完备的文档体系对吸引大家关注以及参与都是非常有帮助的。总之，如果仅仅只有一堆源代码，会让很多人都望而却步，以下简单列举两个非常必要的文档和规则说明。 +要做好一个开源项目的推广，项目内容中除了源代码之外，完备的文档体系对吸引大家关注以及参与都是非常有帮助的。总之，如果仅仅只有一堆源代码，会让很多人都望而却步，以下简单列举三个非常必要的文档和规则说明。 -说明文件（README） +项目总览说明文件（README） -开源项目中的 README 是非常重要的，你可以在 README 里面详细介绍有关这个开源项目的重要内容，包括项目主要功能特性、架构原理、安装部署及部署说明、简要的使用说明、目录文件结构、常见问题说明、交流沟通方式等内容，总之能够让关注者迅速的了解这个项目的基本情况。 +开源项目中的 README 文件是非常重要的，你可以在 README 里面系统介绍有关这个开源项目的重要内容，包括项目主要功能特性、架构原理、安装及部署说明、简要的使用说明、目录文件结构、常见问题说明、交流沟通方式等内容，以便关注者能快速地了解这个项目的基本情况和总体情况。在常见的代码托管平台如 Github、Gitee 上，项目仓库首页默认展示的内容就是这个 README 文件的内容，相当于整个项目的“主页”。 贡献说明（Contributing） -任何一个开源项目，肯定都是希望有更多的社区参与者和贡献者，但是对于参与者可以如何参与项目贡献，并且需要遵循哪些基本规则，比如提交问题的规范，如果是做代码贡献，还有代码相关规范等，以及参与贡献的完整操作流程，这些内容我们可以通过贡献说明文档来说明。另外，我们也可以对项目的社区治理架构及不同等级的贡献者的要求及权力做进一步说明，这些内容整体上构成了本项目在社区参与过程中的一些基本规范。 +任何一个开源项目，肯定都是希望有更多的社区参与者和贡献者，但是对于参与者如何参与项目贡献，需要遵循哪些基本规则，比如提交问题的规范等，如果是做代码贡献，还有代码相关规范等，以及参与贡献的完整操作流程，这些内容我们可以通过贡献说明文档来说明。另外，我们也可以对项目的社区治理架构及不同等级的贡献者的要求及权力做进一步说明，这些内容整体上构成了本项目在社区参与过程中的一些基本规范。 + +用户使用文档 （User Guide/ Getting Started） + +对于开源项目来说，自身的功能与非功能特性固然重要，但如果使用体验不佳甚至很难上手，那么对用户来说门槛会变得很高，特别是对于有意向参与开发的用户来说，如果上手使用都不是很容易，那么参与开发的热情就会受到打击。因此，一份系统完整、条理清晰的用户使用文档，既能帮助普通用户快速上手使用，也能提升潜在开发人员的体验和好感度，进一步增强他们对该项目的兴趣和信心；而且通常开发人员都是从使用开始，发现 bug，或者待改进的“痛点”，从而很自然地提出 issue，并给出建议的解决方案。最后，这里的用户使用文档也可以是项目的技术文档（Document）或者教程（Mannuel）的一个重要入口，让对项目细节感兴趣的用户，可以进一步了解。 具体的开源项目推广方式比较多，宣传和更新维护都是一个漫长的过程，如果你不是明星账户，如 Google 或者 Twitter 或者 Gitee 上高 Star 项目作者，我们新人能做的只能是坚持。以下列举一些常见的方式。