天生我才必有用。——李白

一份 README 只写了几行:Arcane 把说明书全搬走了

先承认一件事:这份文档短得有点离谱

我打开这个仓库,准备读个十分钟,然后写点东西。

结果三十秒就读完了。

一个 logo,一句 slogan——「现代的 Docker 管理,为所有人设计」——一张 dashboard 截图,一排徽章,然后三个链接:文档站、SBOM、Crowdin。

没有功能列表。没有安装命令。没有「快速开始」。没有架构图。没有「为什么选我们」。

项目地址:https://github.com/getarcaneapp/arcane

我第一反应是被耍了。第二反应是——这可能是个决定,而不是一次疏忽。

因为这份文档里每一段都写得很规整:有版本说明,有 issue 政策,有赞助者,有翻译入口。一个随手糊的 README 不会长这样。它短,是因为有人决定让它短。

那就按这个前提来读:一个项目把说明书搬走之后,仓库首页还剩什么。

它到底给了你什么

把所有内容摊平,其实只有四类信息。

一句话的定位。 现代的 Docker 管理,为所有人设计。

一张截图。 文件名写着 arcane-dash-v3-dark 和 arcane-dash-v3-light,说明它认真做了明暗两套。图里是一个 v3 的 dashboard。

一组徽章。 翻译完成度、Go 的包索引、BSD-3 许可、Snyk 的漏洞扫描、还有一个叫 Greptile 的代码审查服务的徽章。

几个出口。 官方文档站、SBOM 页面、Crowdin 翻译项目、GitHub Discussions。

就这些。

值得注意的是那张截图的位置。它被放在整份文档最靠上的部分,比任何文字都靠前。这说明作者对产品的信心不在描述里,在界面上——你去看一眼,比我说十句有用。

这也是这份 README 唯一一次「展示」而不是「指路」。

决定一:文档不在仓库里

最显眼的一句是:安装步骤、配置细节、开发指南,请访问官方文档站。

这是一个很干脆的切割。仓库负责代码和发布,文档负责教人。

好处很实际。文档站可以有自己的搜索、自己的版本切换、自己的导航;可以接评论、接分析、接翻译;可以不用受 Markdown 渲染的限制。而仓库里的 README 一旦长起来,就会变成一份永远和代码不同步的旧手册。

代价也很实际:你在离线环境下什么也读不到。

clone 下来,断网,打开仓库——你只知道它是个 Docker 管理工具,以及它有一张漂亮的截图。你不知道它怎么装,不知道它支持什么,不知道它和 Portainer 有什么区别。

这两种做法的分歧,本质上是「仓库是不是产品主页」的分歧。GitHub 这些年一直在把仓库页往产品页的方向推:About、Topics、Releases、Discussions、Sponsors。而这份文档的选择是:不跟它抢。

我不确定这是对是错。但它至少是一致的——它没有一边把文档搬走,一边在 README 里留半份残缺的安装说明。

决定二:main 是 v3,2.x 留了个分支

文档最上面有一条提示,很短:

main 分支是 v3 版本。上一个 2.x 版本在 release/2.x.x 分支。

这句话只有两行,但它交代了三件事:现在的主线是什么、旧版在哪、以及——升级不是无缝的。

一个项目在做大版本迁移时,最常见的处理方式是假装无事发生:文档里不提,changelog 里写一段,然后让用户在 issue 里自己发现。

而这里把它放在全文档最顶部,用的还是「注意」这种标记。等于在门口贴了张纸:里面在装修,旧房间还留着。

对一个自托管的运维工具来说,这条提示的价值比任何功能列表都高——因为用户升级的时候,手里跑着的是生产环境。

决定三:功能请求搬去 Discussions

第二条提示更硬:

功能请求已经移到 Discussions。新的请求请去那里提,也给已有的投个票;issue 现在只用于 bug 报告,这样能保住 bug 的优先级。

这段话是做产品的人才会写出来的。

因为 issue 列表混着两种东西时,它会迅速失去作用:一半是「它坏了」,一半是「我想要」。前者需要被看见、被排序、被修;后者需要被讨论、被投票、被搁置。混在一起,维护者的注意力就被稀释了——而稀释注意力的成本,最后由那些真正坏了的东西承担。

把两者分开,是一个很成熟的动作。而且它顺手给了功能请求一个更好的去处:投票。issue 没有投票,Discussion 有。

顺便说,这也是一种很体面的拒绝方式。一个功能请求进了 issue,维护者要么修、要么挂着、要么关掉并解释;而进了 Discussion,它天然就是「一个待讨论的想法」,不承诺任何排期。

决定四:SBOM 单独开一页

有一节叫「安全与透明」,只有一句话:在 getarcane.app/sbom 查看 Arcane 的软件物料清单。

就这一句,没有解释什么是 SBOM,没有说为什么重要。

这个处理挺有意思。它假设读到这里的人已经知道 SBOM 是什么——一份列出所有依赖组件的清单。而它把这个清单放在一个独立页面上,而不是塞进仓库。

对一个要接管你 Docker 主机的工具来说,这个动作的分量不小。你给我的东西会跑在我的机器上、能看我的容器、能读我的环境变量——那我至少该知道它里面装了什么。

把清单放在外面,还有一个隐含的好处:它可以被独立更新、独立引用、独立审计,而不需要跟着代码提交走。

没有的那几节,恰恰是最常被写的

一份产品 README 通常有四个固定段落:功能清单、安装命令、架构说明、竞品对比。

这四样,这里一样都没有。

没有功能清单。 所以你不知道它到底是管容器的、管镜像的、还是管编排的。你只知道它是「Docker 管理」,以及它的界面长什么样。

没有安装命令。 连一行 docker run 都没给。对一个 Docker 管理工具来说,这挺反常——它自己的部署方式,本来就是最好的广告位。

没有架构说明。 没有图,没有分层,没有「我们为什么这么设计」。想理解它,只能去读代码或读文档站。

没有竞品对比。 这一条最耐人寻味。做这类工具的人,脑子里一定有一张对照表:谁更重、谁更贵、谁更好用。但这份文档一个字都不提。

四样都缺,可以是自信,也可以是还没写。区别在哪?

区别在于:缺的那部分,别处有没有替代品。

功能清单的替代品是截图和文档站;安装命令的替代品是文档站的 Quickstart;架构说明的替代品是代码本身,以及那个 Go 包索引——能被当库引用,说明结构还算干净。

而竞品对比,没有替代品。它是真的不打算说。

我猜的原因是:说别人不好,是件成本很高的事。要么显得不体面,要么被截图挂到社交媒体上。而这个项目选择了闭嘴——只描述自己是什么,不描述别人不是什么。

这个选择不一定对。但它至少没有把「我们比 X 好」写成卖点,然后在评论区打三个月的嘴仗。

门口挂的五张体检单

那排徽章,其实是一组「第三方证明」。

翻译完成度。 来自 Crowdin,显示有多少语言被翻完了。这条在说:这东西不止英文用户在用。

Go 的包索引。 一个 pkg.go.dev 的徽章,指向 getarcane.dev/arcane/v3。它在说:核心是 Go 写的,而且是可以被当库引用的。

BSD-3-Clause。 许可。宽松,能商用,能改,能闭源分发。

Snyk 的已知漏洞数。 这一条最实在。它不承诺「我们没有漏洞」,它把扫描结果直接挂出来,数字会变,你随时可以看。

Greptile 的徽章。 一个代码审查服务的标记。这条比较少见——它不是在证明「我们安全」,而是在说「我们用 AI 审自己的代码」。

五张单子里,两张是关于「别人怎么看我们」,三张是关于「我们怎么检查自己」。这个配比挺健康的。

顺便说一句,徽章这个东西最容易变成装饰。挂十个没人维护的徽章,比不挂更糟——因为它们会一直显示「passing」,哪怕代码已经三个月没跑过测试。而这五张里,至少有两张是活的:漏洞数和翻译进度,都是会变的东西。

赞助与翻译:两个「把活分出去」的动作

文档里还有两节,都很短。

一节是赞助者,一行字:「这个项目由以下这些了不起的人支持」,然后一张 logo 墙。

一节是翻译,一句邀请:来 Crowdin 帮 Arcane 翻译。

这两件事放在一起看,其实在说同一件事:这个项目的某些部分是别人的。

钱是别人的,语言是别人的。而这两样恰好是一个项目最难靠自己解决的东西——赞助要有信任,翻译要有母语者。

一个愿意在 README 里明确标出「这部分靠别人」的项目,通常比一个假装全靠自己的项目更结实。

最后

回到开头那个「被耍了」的感觉。

我原本想从 README 里读出一个产品的形状,结果只读到了一张门票。真正的形状在文档站里,在截图里,在 Discussions 的投票里。

这是一种很自信、也很冒险的写法。

自信在于:它相信你会点那个链接。冒险在于:大部分人不会。他们会在仓库页面上滑三秒,判断这个东西是不是自己要的,然后关掉。

这份文档赌的是那三秒里,一张 dashboard 截图加一句 slogan 就够了。

够不够,我不知道。但我知道另一件事:一份短得离谱的文档,本身就是一个信号。 它告诉你这个团队把力气花在了别处——花在文档站、花在界面、花在把 issue 和讨论分开这种没人会夸的地方。

至于那些真正想知道「这玩意怎么装」的人,文档站的门一直开着。只不过门上没写「推」,只写了「请进」。

这年头,能这么干的,要么是懒,要么是真有东西。看那张截图,我倾向后者。