我是如何优化开源项目的 README 让 star 反向而行的

首先你以为你的项目写得很好，很用心，花费的时间很多，然后你应应该得到很多支持吗？并不。因为你的代码其实首先写得像 s 一样不堪入目，其次堆得像山一样高。

你以为你写了很多功能，然后这些功能你连自己使用的时候，你都得查你写的文档，并边查边感觉是不是什么地方写漏了，有的功能说明怎么找不到？到底是要用 d.ts / jsdoc 自动生成文档，还是要手动编写文档？

你以为你写的功能很有用，其实那只是你写开发此功能前不对社区或已有的轮子存有包容态度，所以你想自己搞一个，显得好像就是你想要的样子。但其实也并不是别人想要的样子，所以你发现了，你开发的功能只有你在使用，你没有使用的时候，在讨论区根本没有一丝提及和问候。

所以你觉得这可能是使用量太小或者反馈群体太少？所以你添加了各种谷歌统计、百度统计、友盟统计，期望在其中发现蛛丝马迹。后来你感觉这些数据都很单向和冰冷。

有一天，你到相关的技术群组中去咨询大家对这个项目的一些建议的时候，没有一会你就被移除了群聊......

基于开源项目的思考

什么是开源项目

往简单了说，什么是开源项目？你创建了一个项目，名为 X，然后把这个项目公开，这就是开源项目。不管这个项目是不是 hello world，有没有代码。参考 github.com/kelseyhight... 该项目没有 1 行代码，但当前 star 57.2k。

开源的意义是什么

开源的意义是什么？一件事情，只要你认为它有意义，它便有了你的意义。就像前面所列的 nocode，我认为他的意义便是颠覆 github 千千万万个项目的特别的一个项目： nocode 的项目。让人感觉特别？新鲜？这也是它的意义。

那么从广泛情况来讲，我认为的是：我经常在网上(github/google...)去扒拉扒拉别人写的代码来完善自己的项目，也经常得到很多别人写的工具的帮助。但我可能都不知道或不记得作者他们是谁，无以回报。所以某一天假设我也能写一个看起来能帮助到别人的工具了，我也给大家用。

开源的动机或成果是什么
- 人人为我，我为人人。延续共享精神的。 -- 提一句其他观点的话，我经常看到一些观点，说正是程序员开源导致了程序员卷死了自己，因为谁都能使用共享的代码来做项目，那程序员之间的价值便无法体现出来了。
- 借助社区的力量，完善项目。
- 熟悉开源流程。
- 展现自我价值。 -- 这种东西，只是别人了解你的另一种渠道。
- 挖掘项目价值。 -- 如果项目做得好，使用的人多，就注入商业行动。
- 占位、推广。 -- github 上有一些类似的项目，因为有一个已成型的商业项目，然后又在开源社区占了个坑，
如何体现项目价值

应该大部分都是从使用量(引用)、下载量、生态、star、关注度、维护状态等方向进行多维度对比。

我的奥义是什么

从内心出发，应该是先自己用，觉得能帮助到人并且大概率不会被骂太多的话就会给别人用(虽然很多时候故做坚强，但我的小心灵还是挺脆弱的)。

...... 我酸球了，这搞得好像是写自传一样的，越来越偏越来越偏，言归正传：

我在酸什么呢

有时候嘛，看到某些类似不类似项目其实也很平常嘛，完成度也不高，文档也没有，为啥人家就几百 star 了？毕竟我这都几年了，才几十个，我还是挺伤心的。所以问题出在哪呢？

README 祭天的各个版本

大纲结构是这样的：

第一版

讲了项目的使用和每个子项目的地址(子项目下有子项目的文档)。

txt 复制代码

## 安装和使用
## 模块
### WEB页面
### 文档系统
### 发布器
## 服务端

第二版

感觉大家是希望一眼能看出项目是什么东西，然后关心怎么用，模块说明好像没有人看。

txt 复制代码

## 特性
## 使用
### 示例
## 部分功能截图

第三版

发现似乎没什么其他语言的用户支持啊，是不是得为他们考虑下？

txt 复制代码

## 快速使用 quick start
## 常用选项 options
## 问题 Issues
## 贡献 Contribution
## 许可 License

第四版

嗯再把特性、与其他项目的比较、鸣谢这些都列一下。

txt 复制代码

## 特性 Features
## 快速使用 quick start
## 常用选项 options
## 区别 Difference
## 问题 Issues
## 鸣谢
## 贡献 Contribution
## 许可 License

第五版

不对啊，中英混搭算什么东西？那就直接首页都弄成土味英文 README，再换个中文文档切换按钮吧，我看人家项目都是这么搞的。

txt 复制代码

## Features
## quick start
## Difference
## Issues
## Thanks
## Contribution
## License

README 的历程结果分析

上面的土味英文 README 结果是，完犊子了不但其他语言的人不鸟我，连同僚们也基本不鸟我了。

问题出在哪呢？先说说英文的问题，自己的另一个项目 redoc-try 也是这样搞的，然后基本都陆续有国际友人表示支持。

思考下来没有国际友人的 star 可能有以下几点原因：

文档问题

虽然 README 是英文的，但里面链接的文档是中文的，给了人一种十分不好的用户体验。这个应该把文档也搞一份英文的就行，但是我的英文太难了哇！！！

但是我有个小小疑问，示例代码很简单并且都是 js 的哇，照葫芦画瓢就行，并且都是 express 难道他们没文档就看不懂？

代码注释和 git commit msg 问题

注释和 commit msg 是中文的，估计就直接不想看了吧。我能相像我平时看代码看到什么韩文注释时的心情。但我感觉好歹代码本身而言对他们来说就像读母语一样呢，特别是像 js 这种高度抽象的语言。

哦对了，redoc-try 那个项目当时是有个伙计特别提了个 PR 把所有注释都给翻译成英文的了。后来我也按此惯例把 git commit msg 也搞成自己的土味英文了。

文档陆外不能访问的问题

由于众所周知的问题，网站部署在陆外时，境外人员可能访问不到，部署在境外时，陆外人员可能访问不到。部署在三方服务上时，可能不稳定，真是头大。

不过这个问题应该不是大问题，因为反正也没有其他语言的文档，如果有了估计会选择在三方服务上部署(你看 element-ui antd vue 文档这些如果国内 IP 访问时，会推荐你访问国内版)。

项目方向或功能定位问题

最怕的就是这个问题。比如是否可能项目的介绍或名称什么甚至是功能在国际友人看来，他们一般不会使用此类型的工具。这个有待考究，不过 json-server 这个项目如果都这么火的话，应该此项目也不能说没一点人看，估计还是因为其他原因。

README 分析总结

如果一个项目的语言设施不完善，就不要搞，否则不伦不类。我现在就觉得搞个英文 README 但文档却都是中文的，挺三不像的。活该同僚们都不鸟我，star 居然反向而行------呈下降趋势。

好了，那我们再改一版试试吧，现在题纲是这样的，主要添加一定的图片和示例。

txt 复制代码

## 尝试
## 功能示例
### 如何使后端的接口允许跨域
### 如何创建一个自己的接口
### 如何从接口获取请求信息
### 如何快速生成 Restful API
### 如何生成逼真的数据
### 如何更改后端返回的数据
### 如何延迟后端接口的响应时间
### 如何创建一个下载文件的接口
### 如何创建 websocket 接口
### 如何实现动态的接口路径参数
### 如何向后端展示接口参数
### 如何远程使用接口
### 如何恢复后端好了又坏的接口
### 如何在后端关闭时不影响页面
## 从界面上操作 mockm
## 区别
## 友情链接
## 许可

若要拍砖请移步至 github.com/wll8/mockm