尝试在写一个渐近式的 Meow 的教程,求建议

感觉从 Meow (潜在)用户的反馈来说,文档是基本读不懂的。

仔细想了很久,今天突然意识到了这种场景的文档就只能是手册,没法变成教程。说到教程就觉得做个渐近式的教程也许会不错。

https://gist.github.com/DogLooksGood/dae49162928676e6e9691f23feb4a93c

还在制作中,目前没逻辑,要先把所有的文字内容写好。因为 Meow 本来就是要绑键的,所以一边引出一个个的命令,一边让用户跟据喜好绑定,一边对命令进行说明,最后生成一份配置。

如果有人有空提些建议就更好了,非常感谢 :smirk_cat:

先写亮点,勾起用户兴趣后,再展开描述。

现在的文档重点不够突出,看半天看不懂就放弃了

2赞

我也是meow的潜在用户之一,前段时间刚切换到meow https://github.com/GTrunSec/my-profile/blob/master/dotfiles/doom-emacs/meow.org 主要来讲,看不懂或者教程是缺乏直观的相应的func的效果。比如expand replace pop query kmarco和meow的快捷键联立的使用等,这些能够突出meow特点的快捷键使用场景, 应该录制相应的gif,和快捷键的测试数据文本。让用户自己再自己使用感觉。

如前期,我自己都是自己一个一个去测试一些meow func的使用功能,感觉应该是这么使用,或在某个场景下。如果作者本身出相应录制和直观效果说明图,那么就最好了让用户更加直观的去理解本身的功能而个。

1赞

那文档要短,似乎描述放在教程会好些。README 铺开就一定很无聊的样子。

我是一边看readme一边看狗哥的配置配起来的。 现在用的非常舒服

你现在使用的打开方式很可能和我想象的就有很大的区别(猜测)。 我也想过录 GIF,可能做一个有交互式的教程更好,GIF 太多了那个页面会变的特别长,肯定显得更乱。

能看懂 README 的也是厉害,老实说我自己都不怎么看的懂。

这个问题不大,readme尽量保持精炼就好。相关的操作其实可以维护一个hugo theme或者其他文档主题网站,这样清爽又方便,gif或者terminal录制的好处就是针对每个func可以给出精确简短的直观说明。如果维护一个meow相关的doc theme会更加好。org link的帮助会让你各种说明都很有条理,快速。

Evil普及很广了,meow 和 evil 是平级但是适配很可能没有 evil 广,有点尴尬。

如懒猫所言,要突出优点,量化的优点,比如如何证明比 evil 强很多。

Meow 有一个要解决的问题就是 Evil 跟很多的插件适配都有问题,所以需要各种的 Keybinding 和 evil-xxx 补丁插件。所以可能因为 README 的东西太多了这样的内容反而不突出,README 里面大概应该就留下这么几句话,可能别人才会有直观的印象。

恩,readme 里可以像 selectrum 作者那样先把其他按键系统 diss 一遍,然后教程里再具体讲解操作 :smirk:

这么说的话 boon 有这么个 issue。

1赞