为什么我们坚持维护中文文档

一个开源系统被放弃，通常不是因为功能不够，而是因为新用户在前 30 分钟里失败了。

下载、配置数据库、启动服务、登录、创建第一个项目——任何一步卡住，用户就会离开。英文文档不是不存在，而是它假设了太多背景：你可能知道 OpenACS 的包机制，知道 NaviServer 的配置目录，知道 PostgreSQL 的编码要求。但第一次接触的人不知道。

中文文档真正解决的是什么

不是“把英文翻译成中文”，而是补齐上下文：

• 这台机器要装什么版本；
• 命令在哪个目录执行；
• 报错时先看哪里；
• 哪些配置必须改，哪些可以保持默认；
• 出了问题，最小可复现的信息是什么。

所以我们把文档分成四层：开始使用、安装部署、功能指南、开发与扩展。前两层保证“能跑起来”，后两层保证“能改得动”。

一个具体的例子

在英文语境里，“configure your database connection” 是一句话；在真实部署中，它意味着：

1. 数据库是否已初始化；
2. 用户是否有建表权限；
3. 连接地址在容器里是服务名而不是 localhost；
4. 字符集是否支持中文；
5. 修改配置后是否需要重启。

文档把这些隐含步骤写出来，用户才不会在同一个地方反复踩坑。

文档也会过期

维护文档比写文档更难。版本升级、界面调整、依赖变化，都会让截图和命令失效。我们的做法是：

• 每个文档标注更新时间；
• 命令尽量使用可复制的代码块，而不是截图；
• 版本相关的描述写明适用版本；
• 收到问题反馈时，优先修正文档，而不是只回复提问者。

你可以怎么参与

如果你刚刚完成一次部署，记得最清楚的就是你踩过的坑。把过程写下来，就是最有价值的贡献。

• 修正一处错误的命令；
• 补充一个报错的处理方式；
• 翻译一篇核心指南；
• 提供一份脱敏后的部署清单。

不需要等到“完全精通”才开始贡献。文档的读者，往往就是昨天的你。