吐槽龙虾的官方文档:写得像天书一样

忍不了了,必须吐槽一下 OpenClaw 的官方文档。

问题一:新手不友好

文档上来就假设你会 Docker、会 Linux、会 YAML。对于非运维背景的开发者,入门门槛太高。

一个 Quick Start 文档里出现了 20 多个命令,这叫 Quick?

问题二:示例代码跑不通

至少有 3 处示例代码是过时的,直接复制跑会报错。我在 GitHub Issues 里搜了一下,果然有人提了,但一直没修。

问题三:中文文档不完整

英文文档倒是比较全,但中文文档只翻译了一半,而且翻译质量参差不齐。有些地方明显是机翻。

问题四:搜索功能鸡肋

文档站的搜索基本不能用,搜个关键词出来一堆不相关的结果。最后还是靠 Google site: 搜索。

正面的地方

社区的 Wiki 和博客文章质量反而比官方文档高。很多关键信息是从社区帖子里学到的。

建议

  1. 出一个面向新手的图文教程
  2. 维护一个"从零开始"系列
  3. 示例代码要有 CI 保证能跑
  4. 中文文档要么不做,要么做好

文档是开源项目的门面。再好的产品,文档烂了用户就流失了。

终于有人说出来了!Quick Start里20多个命令那段我看了三遍都没搞懂顺序

示例代码跑不通是最致命的。新手按文档来,第一步就报错,直接劝退

建议社区搞一个"文档纠错"的贡献指南。很多人发现了问题但不知道怎么提PR修改

英文文档其实还行,中文文档才是灾难。有些明显是机翻的,看了更迷糊

作为技术写作从业者,OpenClaw的文档缺少的不是内容而是结构。需要按使用场景重新组织

API文档更新不及时的问题真的很头疼。v2.3的API和文档里写的完全对不上

我已经习惯了看源码代替看文档。虽然效率低但至少是准确的

社区有人写了一些非官方教程,质量反而比官方文档好。推荐看Discord里的#tutorials频道

文档写得好不好直接影响社区增长。很多人不是不想用龙虾,是看了文档就放弃了

建议官方搞个文档Sprint,集中一周时间重写核心文档。社区应该会有很多人愿意参与

@fullstack_wu_pro 示例代码跑不通是因为文档写的时候能跑 但版本更新后没同步改 这是开源项目的通病 但龙虾这么火了应该有人专门维护文档

@netjinfan 按使用场景重组文档这个建议太对了 现在的文档是按功能模块组织的 但用户不关心模块 关心的是怎么完成一个具体的任务

@fullstack_xuism 看源码代替看文档 这种做法只有资深开发者能用 新手看源码比看文档更懵 所以文档质量对社区增长太重要了

社区文档比官方写得好

中文文档基本没有

新手被文档劝退无数次