这是一个创建于 1779 天前的主题，其中的信息可能已经有所发展或是发生改变。
前言
大家好，我是开源文档工具 showdoc 的作者。目前 showdoc 在 github 上有 5300+的 star，受到了部分开发者的欢迎。我写这篇文章，是想与大家分享一下我在整个创作过程中所用到的技术以及相关技能。如果你看完整篇文章觉得毫无营养，比某些摸鱼吹水的帖子要更没价值，那可以不再关注甚至举报。如果你觉得还不错，可以让你有一点点的收获，欢迎捧场，加入讨论，甚至转发分享。
任务管理
无论是做自己规划的产品功能，还是做用户反馈过来的 bug，最终都需要把这些点细化成一个个单独的小任务，串联执行（毕竟自己是单个人力）。在这点上，我主要是利用团队看板来实现我的任务管理。团队看板工具有好多，搜索一下就好，我个人目前在用 tower.im
看板上我新建五个清单，分别是“在做”、“要做-高优先级”、“要做-低优先级”、“待定”、“遗留问题”，我这样分类是有技巧的。首先，它有优先级划分，保证先做重要的事。其次，它有状态管理，方便我随时中断某个任务，过一段时间再回来继续任务。同时，它也能应对新任务——比如说新需求进来，我先放在“待定”，等有空了再分配到其他清单去。最后，它还有“遗留问题”清单，可以让我不在某个“疑难杂症”上卡住太多时间，快速推进下一个任务。
本地开发
用 Linux 或者 MAC 会非常方便开发、搭建测试环境等，对开发者的方便是毋庸置疑的。但是电脑有时候需要玩游戏，需要装一些专业大型软件。从兼容性和广泛性的角度来考虑，我个人还是使用 windows 系统。在 win 上，我使用的是 Vagrant + virtualbox 这个组合。Vagrant 是一套工具，帮助你快速在 win 系统上，利用 virtualbox 搭建起虚拟机，从而方便使用 linux 或者 MAC(比如上架苹果 app 的时候我需要 MAC 虚拟机)。关于这点，可以参考我几年前写的一篇教程：blog.star7th.com/2015/06/1538.html
代码管理
我用 git 作为代码版本管理工具，同时使用 tortoisegit 进行可视化操作。 说一下我是怎么维护官网在线版 showdoc 和开源版 showdoc 的。我在自己的服务器安装一个私有版的 gogs 作为私有 git 管理平台。功能开发好了，我再推送到 github 上去。官网版和开源版一开始是同一个仓库里的不同分支。后面它们的差异（尤其是后端代码的差异）越来越大，所以我干脆把它们分成两个不同的仓库了。做开发的时候，我一般是现在官网版上做开发以及测试验证，然后再用 tortoisegit 的代码修改差异比较功能，把功能迁移到开源版去。
说一下分支管理策略。我至少建立两个分支——主分支和开发分支。新功能会在开发分支做，验证好了再合并到主分支来。用开发分支的时候也有技巧。比如说，一个大的功能可以基于开发分支再新开一个分支去做。例如我今天想做 A 功能，那就在 A 分支上操作。但是 A 功能遇到瓶颈了，这会儿我暂时没精力去找 bug，所以此时我可以再基于开发分支开启 B 分支，继续做 B 功能。这很重要，因为在人力有限的情况下，我做什么事情都是串联的，同一时刻只能做一件事。这样的策略有利于保证自己随时中断、随时上手任务，灵活地安排不同的时间去处理容易的或者棘手的问题。这个过程也需要配合上面说到的团队看板使用。中断前要记录好进度，方便自己随时恢复工作。
shell 自动化脚本
我为 showdo 写了三个 shell 自动化脚本。其作用分别是自动化部署 showdoc，自动生成 api 文档到 showdoc，自动生成数据字典到 showdoc。之所以选择 shell 而不是其他脚本语言（如 python ），是因为 shell 基本可以运行在绝大部分 linux 上，部分运行到 win 上（需要安装工具），兼容性超好，依赖非常少。根据反馈，受到的好评比负面评论多得多。自动化脚本大大节省了使用者安装环境的麻烦，降低了 showdoc 的使用门槛。showdoc 大部分的用户不是 php 开发者，要他们安装 php 环境还是挺折腾的。有了一键脚本，他们用得方便，我也省心，不需要在解决新手反馈上花太多功夫。这个方法是具有普适性的，并且语言无关（因为一键脚本使用 docker 跑服务）。是可以大量应用到开源项目中，非常有利于开源项目的代码分发。
顺便强调一下，做 web 应用开发的人，尤其需要克服一下对 shell 脚本的疏远感。我以前以 web 开发为主的时候就会潜意识地疏远 shell。在腾讯的时候向另一个技术栈的同事请教了下，发现其实还是蛮简单的。只是因为自己过去心理上的疏远感导致自己没想过要去写 shell。跨过这个心理槛，就会扩展自身的能力边界，写起来跟其他语言没有太多区别，仅仅是需要多搜索查询下语法而已。
后端开发
可能是因为 showdoc 仅是一个小产品，涉及到的后台逻辑并不复杂，所以我在开发后端花的时间不多，基本上都是 CRUD，对数据库进行增删改查操作。需要多动点脑力的地方在于团队管理功能，新建多几张数据表联合实现精细化权限控制。
showdoc 后端主要采用的是国产框架 thinkPHP。这个框架有好也有不好。不好的地方在于它的框架约定、生态共享比较一般，好的地方在于它可以快速撸出一个东西来，而且兼容性还可以。这是四年前我刚开发 showdoc 时的决定，后来也懒得换框架重写了，所以沿用至今。技术是相对落后了一些，但是也胜在兼容性好，可以兼容老的 php 环境和一些老的服务器。这个还是挺重要的，因为 showdoc 是开发辅助性质的工具，协助写文档。兼容性越好就越容易被各种各样的群体接受。个人觉得这一点比用各种先进技术要更实用一些。当然了，如果是现在新开发其他项目，我应该会使用 laravel，或者 NodeJS 写的 eggjs。
前端开发和 UI
我在前端开发上花费的时间比后端开发时间多很多。可能是因为这是个体验型产品，需要把前端体验做好。起步一个产品的前端页面时候，我建议一定要选好一个 UI 框架。比如我选择的是 ElementUI 做 showdoc，而 runapi 则使用 museUI （ runapi 是辅助 showdoc 用的一个在线 api 测试工具）。
showdoc 用的编辑器是 editor.md ，是几年前的产品。虽然说它代码组织方式可能有点落后，且原作者似乎有放弃维护的趋势。但我觉得它功能强大且简洁美观，所以我花了时间将它封装成了 vue 组件，并且修改其源码增加了安全性。
项目拖拽和页面排序我用的是 vue 组件 vuedraggable，还蛮好用的。以后有拖拽的需求我估计还是用它。
图标设计方面，可以使用 UI 框架内置的字体图标，也可以用阿里妈妈的矢量图标库。或者自己使用 Iconion 进行图标设计。这里我强调一下 Iconion。这个工具可以非常简单快捷地使用一些预定的图案和背景，组合成一个快速可用的产品图标。showdc 的产品图标就是这样制作的，快速省时地做到媲美专业的效果。如果以后把产品做大了，可以考虑请设计师设计。但在项目前期，用 Iconion 就够了。
在这里要提一下前端技能的重要性。虽然说 UI 框架以及相应的工具能够帮助你节省很多时间。但如果想做好一个产品的体验，那么其涉及到的 UI 和交互可能超出框架自带的范围。因此自己必须学会使用原生 css，会 js 交互，会封装组件。而且，前端技能跟下面要说的 app 多端开发也有帮助。
app 多端开发
关于移动 app 产品原型设计，我很建议使用“墨刀”来做简单的原型规划。有了一个可视化的原型，真的能节省很多大脑时间，让你在开发阶段的时候可以专注代码，而不需要写一下代码，又回头思考下一步做什么功能，这样的来回切换相当耽误效率。
app 开发我用的是 uniapp，使用 html5 等前端技术把代码封装成手机本地 app，包括安卓 app、苹果 app，甚至小程序。这种技术几年前就有了，但是性能一直不温不火。2019 年的时候我看到了这块发展得还是可以的。所以就产生了做 showdoc app 端的想法。不过由于 showdoc 重在 pc web 端，手机只是起到辅助作用，所以我没有很精心去做。大概把 web 版简化一下，复用一些组件，重写下前端，然后就上线了。顺便说一下，我做得比较精细化的 app 是时光树洞（ blog.star7th.com/2019/09/2380.html) ，这款 app 的 UI 就花了点心思。
如果要让我评价这种混合型 app 和原生 app，我会说，肯定原生 app 最好。只是出于成本和人力的考虑，对一些展示型的、交互体验要求不那么高的产品，可以采用这种 h5 技术处理。大家如果在验证市场阶段，可以采用类似技术快速做一个可用产品出来。
此外说一下苹果 app 上架的问题。我是利用虚拟机安装了一个黑苹果系统，然后装相应工具，把 app 上传到苹果商店去。关于如何开通苹果开发者账号，如何在虚拟机安装苹果系统，这个你可以自行搜索。
用户反馈和社区运营
一开始，用户反馈消耗了我不少精力。敢情自己成为一个客服了。后来我开始做了一些改变，基本把自己从这些反馈中抽身出来了。
首先我分开了官网在线版和开源版的反馈，开源版的反馈统一到 github （ gitbug 的使用门槛能过滤掉一些非常新的新手，避免新手问题），在线版的反馈统一发邮箱。有功能或者 bug 要改，我先记在团队看板。而对于一些常见问题，我整理好了文档，和一些固定的回复术语。另外我也开了三个 qq 群，供 showdoc 使用者自身交流。不过我要提的一点是，千万别试图回答 qq 群里提的每一个问题，会把人逼疯的。所以我更改了群公告，改写了群定位，将 qq 群定位为用户自行交流的地方。让热心用户去回答新手在使用 showdoc 时遇到的问题。而我则只需要很偶尔看一下。需要官方的支持还是让用户走 github 或者邮件通道。
不过值得一提的是，我这种运营思路是不适合所有团队的。我是人力有限，效率优先，所以过滤了很多不太必要的反馈。假如说有很足够的人力，我倒建议可以多花时间帮助用户解决问题，既扩大用户量，又提高产品口碑。
后记
先讲这么多。其实还有很多东西可写，上面很多点也可以细化成一篇篇独立的文章。先看看用户反响吧。如果没人看，那就这样吧。如果有不少人觉得有帮助，我再写点什么，或者扩充上面的小点成独立文章，发出来或者写到自己的博客上。
 |
1
zhuawadao 2020-01-13 09:58:15 +08:00
点赞
|
 |
2
chnyung 2020-01-13 10:01:02 +08:00
已收藏！点个赞
|
 |
3
EKkoGG 2020-01-13 10:08:23 +08:00
谢谢分享
|
 |
4
dongisking 2020-01-13 10:09:59 +08:00
内部使用过，简洁方便好用。其实很多人都没搞明白，接口文档根本不需要那么花花绿绿的功能，把核心做好就够圈一波用户了
|
 |
5
Mzs 2020-01-13 10:10:21 +08:00
支持 在上家公司中用的不少 蛮好用的
|
 |
6
star7th OP  2
10 个收藏，5 个回复，什么鬼！多点互动反馈好不好，否则我觉得花那么多时间精力去总结文字没有太大价值啊。
|
 |
7
isleon 2020-01-13 10:24:10 +08:00
楼主思路很详细,帮助良多.
|
 |
8
qiguai2017 2020-01-13 10:26:41 +08:00 1
现在纯 star 数没太多意义，真要分享自己的成果，最好贴出这个产品最近一年的 pv, uv, 独立 ip 访问量等数据。
|
 |
9
fengshils 2020-01-13 10:29:01 +08:00
点赞
|
 |
10
noqwerty 2020-01-13 10:29:03 +08:00 via Android
谢谢分享！请问 vagrant 比 wsl 开发的优势在哪？
|
|
11
star7th OP @qiguai2017 不不，这个不是一个秀战利品的帖子，分享了很多技巧，是对别人有用的。单纯贴数据，对别人的帮助有限。
|
|
12
star7th OP @noqwerty 我没有比较。主要是我几年前用 vagrant 的时候还没有 Windows Subsystem for Linux，所以不评价它。现在我是沿用之前的开发习惯继续用 vagrant。假如说 Windows Subsystem for Linux 挺好，也可以用的
|
 |
13
jackchao7432 2020-01-13 10:32:55 +08:00 12
6 楼这一句话让我对楼主的印象跌入谷底....
|
 |
14
sniperking1234 2020-01-13 10:35:43 +08:00
@star7th 收藏难道不是对你总结的肯定吗
|
 |
15
zhoushiya 2020-01-13 10:36:42 +08:00
给楼主点赞，这么一篇文章居然没有放项目地址，也没有官网链接，可见不是广告，是纯分享
|
|
16
star7th OP @jackchao7432 做事情需要共赢思维。如果说一个人花精力去写的东西完全没反馈，会打击分享热情的。最好的方式是大家共赢，你看了，对你有所启发有所帮助，对我而言有足够的反馈动力。
|
 |
17
lanye233 2020-01-13 10:38:15 +08:00
感谢分享~赞！
|
|
18
star7th OP 1
@sniperking1234 我复制一下前面的话。做事情需要共赢思维。如果说一个人花精力去写的东西完全没反馈，会打击分享热情的。最好的方式是大家共赢，你看了，对你有所启发有所帮助，对我而言有足够的反馈动力。
而且我不单纯想看到别人的肯定，我也想探讨一些问题。比如说我上面有哪些创作方式是可以改善的，更加有效运作的。像前面有人提到 Windows Subsystem for Linux，这就是我想看到的互动。 |
 |
19
memedahui 2020-01-13 10:46:24 +08:00
在用,不过 icon 太多没有文字说明,导致每次点之前都要想一下对不对.
|
|
20
star7th OP @memedahui 这个设计我是经过考虑的。首先，这些按钮在鼠标放上去的时候都即时地显示出文字，可以很好地引导用户。而当用户用习惯了，那么就差不多记得这些按钮地用途了。这个时候还展示文字的话，反而占据了视觉空间，显得不够简洁。
|
 |
21
Zoro76 2020-01-13 11:01:21 +08:00
支持一下
|
 |
22
test3207 2020-01-13 11:11:29 +08:00
之前用过，有一些不太方便的地方：
批量删除文档（文件夹）； 文档排序； 文档删除好像只是做了删除标记，实际上数据库会越来越大； 后来全干之后就不用了 XD |
|
23
star7th OP @test3207 你说的这几点在新版都解决了啦。比如说可以一并删除一个目录和目录下的页面；目录排序和文档排序都改用了拖放方式。文档删除一开始只做标记，但是会定时清理的。这个是当初埋下的隐藏功能。现在已经把这个功能扩展为回收站功能。
|
 |
24
hengtong 2020-01-13 11:24:56 +08:00
点赞
|
 |
25
DiamondY 2020-01-13 11:38:18 +08:00
本来看到标题想进来吐槽一下的，但看到正文和评论，感觉走错片场了，默默留下这条评论就溜了
|
 |
26
outside 2020-01-13 14:31:05 +08:00
淘宝的 Rap2 他不香吗，http://rap2.taobao.org/
|
 |
27
xiaomingVTEX 2020-01-13 14:47:08 +08:00
点赞, 现在正在内部推广使用, QQ 群这些确实不太适合
|
 |
28
ResidualWind 2020-01-13 14:59:18 +08:00
楼主 NB!
|
 |
29
imzhaotao 2020-01-13 15:07:09 +08:00
点赞 我们团队用了 showdoc
|
 |
30
mnssbe 2020-01-13 15:26:38 +08:00
@jackchao7432 人家用心写了项目,写了文章. 期待有些反馈, 你跌入谷底的点在哪?
|
 |
31
npe 2020-01-13 15:38:42 +08:00
我认为 swagger 已经满足需求了。
swagger 配合注解生成文档，既可以可以生成接口文档，也可以代替代码注释，一举两得。 |
 |
32
afirefish 2020-01-13 15:45:47 +08:00
支持作者，现在也在用 showdoc
|
 |
33
purensong 2020-01-13 16:22:22 +08:00
支持作者，真正帮助到了很多人，我也是其中一个
|
 |
34
onfuns 2020-01-13 16:39:40 +08:00
用的是淘宝的 rap2。有机会试试这个。
|
 |
35
baronOvO 2020-01-13 16:51:18 +08:00
大佬 NB ！
|
 |
36
encro 2020-01-13 16:55:27 +08:00
*感觉* 隔壁 wisteria 看起来界面更清新，安装更方便，但是 star 比 showdoc 更少？
能否比较下同类给大家一个选择的理由呢？ |
|
37
encro 2020-01-13 16:57:19 +08:00
希望包含 EOLINKER 这种商业级的，让大家对 showdoc 的定位有一个了解。
|
 |
38
Simle100 2020-01-13 17:02:58 +08:00
之前用 showdoc，后来换成 swagger 了，因为 swagger 不用另外写单独的文档。
|
|
39
star7th OP |
 |
40
lower 2020-01-13 17:10:19 +08:00
给作者点赞，以前用过这个项目，当时因为密码的问题还给作者发过邮件求助。
记得当时为了测试 api 方便，给项目提过在线测试 api 的 pr 哈哈，后来好像有老外想用，作者就重构加了国际化支持 当时 qq 群里确实几乎全是最基本问题，甚至是跟项目无关的计算机小白问题……😂 |
|
41
star7th OP |
|
42
star7th OP @encro 我不贬低他人。我一般只说 showdoc 哪里好，不通过比较来说别人坏。我既然坚持做 showdoc，自然心里会有自己的想法，并且觉得 showdoc 依然有它的优势。如果你想讨论，你可以另外开贴，我会去回帖一下。但我就以自己的名义开贴公开讨论了，免得别人说我贬低他人作品。
|
|
44
encro 2020-01-13 17:33:20 +08:00
@star7th 感谢开源，以及分享的内容。
比较，不是贬低，也是让大家对产品的定位有一个了解吧，方便大家做选择。 毕竟各种选择也是很烦人的，我曾今做过一些比较，哪怕很简单的，都很费时间。 内网穿透工具比较(ngrok,frp,lanproxy,goproxy,nps) https://c4ys.com/archives/1927 开源 CRM/ERP 比较 https://c4ys.com/archives/1981 提出这个要求， 就是因为公司内部打算年后上一个内部知识管理，考虑过 wik、语雀、tapd，showdoc 也可以作为一个选择， 以及一些接口目前有部分同事在用 EOLINKER (以前用 postman,httpie 等)， 发现找产品，部署环境，测试确实费时间。 已经发布了一个主题： https://www.v2ex.com/t/637576#reply0 （内网知识库+api 文档，大家都用什么软件？） |
 |
45
herofire 2020-01-13 17:40:37 +08:00
点赞+收藏，楼主是个实在人
|
|
46
star7th OP @encro 你说你发布的那个主题我访问不了，我不知道你发到哪个节点去了。
我访问不了是因为没绑定手机。v2 我一直 github 账户登录，还没绑定手机。而当绑定手机，它提示我要原密码，而原密码我又忘记了，所以不折腾了，就没绑定手机。 |
 |
47
kaychen 2020-01-13 17:53:51 +08:00
给作者点赞!
|
 |
48
superbai 2020-01-13 18:51:35 +08:00
点赞楼主
|
 |
49
albyBen 2020-01-13 23:46:51 +08:00 via Android
点赞（｡ò ∀ ó｡）
|
|
50
star7th OP 1
@encro 我在这里回答一下你吧。首先你们要考虑使用在线服务还是内网部署服务。如果是内网部署服务，你基本不能再考虑 tapd/语雀 /EOLINKER 等。这些要么不能内网部署要么部署成本太高，不如免费开源的 showdoc。
如果你不介意要不要内网部署。那么—— 首先你要做的是知识管理，不单单是程序员使用，也不单单是管理 api，所以像 EOLINKER 之类的也不太适合你。这类产品专业性比较强，基本只适合管理 api。 tapd 我不知道外网版的如何，我只在腾讯时候使用过内网版。我觉得 tapd 在项目管理上很强大，但是 wiki 功能比较弱（这个工具一开始就把 wiki 定位为辅助性工具）。如果要做专门的知识管理，不是很建议。 传统的 wik 功能比较强大，但是界面一般，用户体验一般，我个人是很不习惯用的。 语雀是一个不错的产品。但它为了照顾更大群体使用者，引入了一些需要额外理解的概念，比如企业空间，以及其他。在应付中大型复杂组织可能会适用一些。只是对新手可能要花点时间去理解。showdoc 定位于简单好用，可以管 api 可以写知识文档，非常适合扁平化的 IT 团队，把易用性和性价比发挥得不错。 这是我个人的选择建议。 |
|
51
encro 2020-01-14 09:22:22 +08:00
@star7th
是的， 正是因为 EOLINKER 太偏 api， 语雀太重， tapd 项目管理可以，但是对于开发人员来说，更加乐意 wiki 或者 markdown 形式的所见即所得编辑，传统文件格式用得别扭，和钉钉有所重合， 所以一直还没有决定。 我的需求是外网能够登录后访问，大部分项目对企业内人员开放，部分项目文档需要对外开放（对外包客户端开放接口文档）。 |
 |
52
jasonwxj 2020-01-14 09:50:47 +08:00
点赞
|
 |
53
vsheyan 2020-01-14 10:13:18 +08:00
一会可以再发一篇 我是如何把 github 做到 6000 + star 的.
|
|
54
star7th OP @vsheyan 会被质疑的。这篇的质疑少一些是因为确实有很多干货。如果再发一篇就不合适了。另外我觉得，很多 markdown 类开源项目因为收集了一些教程 /资源而获得了高关注。这让我们这些实打实做代码开源的项目黯然失色。现在我尽量让自己的项目获取多一点的关注，都被小部分人质疑。长此以往，劣币驱逐良币，做开发类的开源项目更难了。
|
 |
55
sunnyswsh 2020-01-14 12:43:04 +08:00
干货很多，点赞
|
Select Language