倡议: 插件开发者尽量要写"用户友好"的文档(不一定要有, 有了更好).

闲聊灌水
1

声明:
鉴于 abo-abo 是一个对 emacs 有贡献的大神, 为了避免争议, 做此声明.

本文的举例毫无针对的意思. 只不过这是最近使用过程中接触到的痛点案例, 自然而然拿出来举例.

相反, 本人对于 emacs 提供插件的开发者的努力和贡献充满了尊重和感激.

这篇帖子的吐槽是基于以上基础写出来的, 语气是轻松的, 态度是端正的. 稍息, 立正, 敬礼.

我发现很多时候, VSCode有的Emacs都有, 但是 VSCode 往往新手友好得多, 插件一点就安装, 安装完马上就可以用了, 或者稍微看一下插件文档, 改一二个配置就可以用了.

Emacs 的很多插件要到能用程度往往需要更加曲折的过程, 甚至还出现了 “你难道不会自己看源码吗?” 这种声音…

试举一例, 同样是实现从系统剪贴板复制图片到文件中这个功能. VSCode 的 PasteImage 安装即使用, 图文并茂,不到 2 分钟就达到了目的. 大家可以看一下 Paste Image - Visual Studio Marketplace

而实现相同功能的 org-download 下载完插件, 看完文档, 还是不知道怎么样配置较好, 最后 google 了五六个别人的配置, 不断尝试, 花了好几个小时最终达到比较满意的效果. GitHub - abo-abo/org-download: Drag and drop images to Emacs org-mode

插件开发者开发了插件, 同时也是插件的使用者, 如何使用并且达到某种最佳实践应该是很清楚的. 多个标题 “推荐这么使用哦, 我就是这么用的哦.”,“最小化插件使用配置你可以这样哦” 并不难.

我的观点没有统计学的支撑, 就我使用经历来讲, 纯粹个人的观点, 同样是上百个 star 的插件, VSCode 的插件开发者更希望一开始给用户一个可用的配置, 并且更希望通过截图,录制 gif以及更详细的usage 来分享自己的插件.

这当然是一种苛求, 只不过是一个倡议, 有冒犯之处, 还望见谅.

5 个赞
2

我觉得有几个原因吧

  1. 开发者做插件首先是为了解决自己的需求，放在网上是出于纯粹的好意，让别人使用学习，遇到问题自己提issue，文档就懒得写多好。
  2. Emacs社区是一个古老又喜欢折腾的社区，深受黑客文化毒害（？），讨厌纯粹的伸手党；很多插件有非常强大的拓展性，一个个例举到文档就太麻烦了，还不如给个简单的README，剩下的让用户自己去折腾。
  3. VSC是典型的新兴社区， 而且在年轻人尤其是高中生大学生中特别受欢迎，里面有不少代码都不咋会写的萌新，让他们自己研究太难了，README写清楚能节省很多issue。(stereotype，不要太认真)
  4. 用户数和社区参与度的问题。好文档不是一天写成的，你可以发现很多文档好的项目都相对比较大，有非常多的用户和活跃的社区。而这些项目一开始的文档都不怎么好，是长年累月由用户和社区通过issue论坛的讨论一点点积累起来的。VSC社区比Emacs社区大太多了。

我挺赞同你的倡议的，在我的M-EMACS和跟懒猫一起维护的EAF项目中我都非常注意README和Wiki文档的准确性和有效性，一个README写得好的项目往往能吸引更多的用户。

其实Emacs社区有不少文档非常好的项目，比如lsp-mode以及ivy。

4 个赞
3

Emacs 从来没对新手友好过呀，用 Emacs 的都是喜欢折腾的。

感觉楼主举的例子也不是很有说服力，与其「google 了五六个小时」，不如直接看代码。 好奇是什么配置让楼主觉得 org-download 不开箱即用，我记得当初没花几分钟就配置好了，并且还在论坛分享过。

4

:rofl: Emacs 的插件有时候比起插件更像是库，要以调包侠的觉悟来使用（（（

2 个赞
5

开发一个插件很有可能不被别人认同，自己认为好用的东西别人不一定觉得好用。

事实上很多插件都是从个人的配置分出去的，可能一开始只是一些自己的函数，慢慢就发展成了插件。你完全可以宣传自己的插件，但是没有什么文档，因为只是应证一下别人是不是对你写的东西有兴趣。如果有一些人有了兴趣，这个时候在考虑写文档，毕竟写文档是非常耗时间的事。

3 个赞
6

pasteImage 安装好之后, 直接在 Markdown 直接按快捷键就可以使用了.

Emacs 的 org-download 官方文档直接简单地列了一点函数 api. 在默认假设使用者能写出你所分享的 79 行配置的情况下, 才能使用相同的功能.

五六个小时是夸张的表达手法, 没那么久. 但我起码看了五六个人的配置, 然后猜测函数作用, 尝试配置, 运行观察结果, 最终达到自己满意的状态.

什么配置让我感觉到不开箱即用? 就是实现跟你分享功能差不多的配置, 让我感觉不开箱即用.

我实现的版本是

  1. 按下 alt+ctrl+y , 就在当前文件的 images/当前文件的名字/ 目录下创建剪贴板的图片
  2. 在 org 文件中插入相应的图片格式
  3. 去掉 org 图片链接上方自动生成的 #+Download 标记

其中 3 的功能涉及的函数, 首页 readme 是一丝一毫都看不到的, 就是你所说的要看源码才能知道.

7

这玩意儿代码我看了看也才700行,如果略通elisp自己过一遍也不难.

不懂elisp的话,你开个issue,问题描述的详细点就好

问了之后,解决方案在issue里贴一下,方便后人乘凉

8

我是觉得既然选择了 Emacs，就不可能「开箱即用」，看源码是最实际、最准确的方式。

对于 org-download 还好，代码不多，对于想 magit/lsp-mode 重量级的扩展，代码量多很多，遇到 Google 不出来的问题，一般只能慢慢看相关实现了，所以这类扩展我一般不轻易升级。

就事论事，如果楼主觉得 3 涉及的功能十分影响用户体验，可以提 PR 来把相关解决方案加到 README 里。

写文档不是开发者一个人的事，也包括使用者。

2 个赞
9

良性的开源应该：

  1. 用户有使用问题
  2. 用户向上游反馈(issue)/提出修改意见(pr)
  3. 上游收到反馈
  4. 上游做出改进
  5. 所有用户受益
  6. 吸引更多用户
  7. 出现更多问题更多反馈
  8. 良性循环

比较差的开源：

  1. 上游不听反馈
  2. 用户不向上游反馈而是自己在别的地方吐槽
  3. 没人受益
8 个赞
10

写文档当然不仅仅是开发者一个人的事情, 这点我和你都没有分歧.

我们的分歧在于 : 我认为写一个表意足够清晰, 并添加上自己的最佳实践的文档是开发者的基本素养.

如果从使用的角度, 看源码是低效的方式, 一个良好组织的 API 文档, 配合使用案例才是软件界的规范. 如若不然, 所有著名的开源的库, 只要开放源码就可以了.

11

如果你觉得有必要增加文档和用例，可以直接联系作者，比如在 github 上加个 issue，甚至可以自己写好让作者加上。

2 个赞
12

顺带一提,你的用词我觉得不太妥当:

前面也有很多人提到了,写插件不是一个强制任务,都是自愿活动.

一个自愿活动不应该被"应",“自觉"所困扰,我能想到的词大概是"尽量”.

插件维护下去,很多api作者自己都不用,如果你不去提issue,永远没有现成的best practice.

2 个赞
13

已经修改为尽量. 对标题还有什么建议? 我都可以一并修改, 我措辞尽量委婉, 不让人产生不舒服的感觉.

1 个赞
14

恩. 好的. 我已经开始按照你的说的做了.

15

我看了 GitHub - mushanshitiancai/vscode-paste-image: paste image from clipboard to markdown/asciidoc directly! 的代码。实际上vscode插件的作者文档没有abo-abo写的全。都要在Linux下安装xclip。 VSCode插件 Paste Image - Visual Studio Marketplace 一个字都不提。abo-abo上来罗列了一大堆命令行工具。

VSCode插件作者技术路线比较讨巧，Windows下用Powershell，macOS下用applescript，保证这两个操作系统开箱即用就行了。如我这样的Windows 7用户只能自求多福了。

3 个赞
16

为了避免被你说中这条, 我已经向上游反馈了.

我向上游反馈, 并且在别的地方做了善意的吐槽.

3 个赞
17

这个帖子看下来，我觉得你的态度和行为值得赞扬。:+1:

1 个赞
18

我已经在这个论坛里回过太多拿 vscode 和 emacs 比较的帖子了。

我觉得 vscode 和 emacs 的定位是不同的。

  • vscode 是开箱即用，但是一旦行为不符合用户期望，hack 起来会比较麻烦
  • emacs 正好相反，初始配置看起来吓人（其实习惯了也蛮舒服的，楼主说的情况对多年使用emacs的人来说根本不是个事），但是 hack 起来很舒服。

举一个我最近 hack org-download 的例子：

在这里我想要修改 org-download 的行为，想修改图片保存位置，org export 链接，在 images 路径下添加文件名这一级目录，这些就通过简单的写几个函数，advice，hook，然后再加上 dir-local 文件，完全搞定。而且这些 hack 只对 posts 目录下的文件生效。这里没有用到任何外部工具，完全只是用了emacs自身的特性。

有了 emacs lisp 的经验实现这种定制非常容易，但是换到 vscode 的话，如果想实现和插件作者推荐用法不一样的玩法，估计你在苦读文档之后，不借助其它工具都不一定实现得了，而且实现了以后插件打包等等烦心事估计也会把你烦死。所以vscode这种工具让我完全没有hack的欲望，因为完全改不动。而 emacs 不管碰到什么问题，我都会产生“也许这里我可以改一点“这样的感（错）觉 :joy: ，所以我觉得楼主说的缺点从另一个角度看可能正是 emacs 的优点。

还是那句老话，emacs 成也 elisp，败也 elisp。

Edit：抱歉，有感而发，有点跑题

3 个赞
19

楼上说的都是啥……谁说只有vs code，明明大部分emacs插件也会给个最简setup代码给你copy paste好吧……甚至很多会分package.el怎么用、use-package怎么用、elget怎么用、quelpa怎么用、spacemacs怎么用给你按需求copy。我去看了同样abo-abo写的ivy的手册，就是这样的，甚至告诉了你中间要按M-x还是啥……org-download写得简单只是因为他觉得这个东西用的人少/用的人比ivy的用户高级一点点，不需要手把手教怎么install，或者他时间有限，只有一份写how to install的时间，于是就给了用户多得多的ivy。

反正不是因为abo-abo不愿意写文档……

20

是啊，abo-abo 的代码风格都是极简的（commit message 写得都很工整 :joy: ），基本上都是够用就行。函数文档写的也很清楚，真有问题，其实用 describe 就能解决差不多了。而且，人极好，回复非常及时。

刚刚意识到楼主吐槽了emacs插件界的大神 :joy: ，可能还是用得少吧，你用多了会喜欢上他写的插件的。