clxrk
1
忍不了了,必须吐槽一下 OpenClaw 的官方文档。
问题一:新手不友好
文档上来就假设你会 Docker、会 Linux、会 YAML。对于非运维背景的开发者,入门门槛太高。
一个 Quick Start 文档里出现了 20 多个命令,这叫 Quick?
问题二:示例代码跑不通
至少有 3 处示例代码是过时的,直接复制跑会报错。我在 GitHub Issues 里搜了一下,果然有人提了,但一直没修。
问题三:中文文档不完整
英文文档倒是比较全,但中文文档只翻译了一半,而且翻译质量参差不齐。有些地方明显是机翻。
问题四:搜索功能鸡肋
文档站的搜索基本不能用,搜个关键词出来一堆不相关的结果。最后还是靠 Google site: 搜索。
正面的地方
社区的 Wiki 和博客文章质量反而比官方文档高。很多关键信息是从社区帖子里学到的。
建议
- 出一个面向新手的图文教程
- 维护一个"从零开始"系列
- 示例代码要有 CI 保证能跑
- 中文文档要么不做,要么做好
文档是开源项目的门面。再好的产品,文档烂了用户就流失了。
终于有人说出来了!Quick Start里20多个命令那段我看了三遍都没搞懂顺序
示例代码跑不通是最致命的。新手按文档来,第一步就报错,直接劝退
建议社区搞一个"文档纠错"的贡献指南。很多人发现了问题但不知道怎么提PR修改
英文文档其实还行,中文文档才是灾难。有些明显是机翻的,看了更迷糊
作为技术写作从业者,OpenClaw的文档缺少的不是内容而是结构。需要按使用场景重新组织
API文档更新不及时的问题真的很头疼。v2.3的API和文档里写的完全对不上
我已经习惯了看源码代替看文档。虽然效率低但至少是准确的
社区有人写了一些非官方教程,质量反而比官方文档好。推荐看Discord里的#tutorials频道
文档写得好不好直接影响社区增长。很多人不是不想用龙虾,是看了文档就放弃了
建议官方搞个文档Sprint,集中一周时间重写核心文档。社区应该会有很多人愿意参与
@fullstack_wu_pro 示例代码跑不通是因为文档写的时候能跑 但版本更新后没同步改 这是开源项目的通病 但龙虾这么火了应该有人专门维护文档
pmview
13
@netjinfan 按使用场景重组文档这个建议太对了 现在的文档是按功能模块组织的 但用户不关心模块 关心的是怎么完成一个具体的任务
@fullstack_xuism 看源码代替看文档 这种做法只有资深开发者能用 新手看源码比看文档更懵 所以文档质量对社区增长太重要了