我为什么要用中文写项目文档

本贴最后更新于 838 天前,其中的信息可能已经时移世易

English Please

最近 B3log 开源社区下的项目 BND1 以及 30s2 被外国友人 hobolance3 贴了两条建议:

  1. English Please - BND4
  2. English Please - 30s5

这两个项目都是中文写的 README。他建议把中文换成英文,这样对外国友人更友好,也能为项目获得更多关注。

What is the problem with Chinese README's
What we want
How this will help you

结尾引用了 Richard Stallman 的名言:

Sharing knowledge is the most fundamental act of friendship. Because it is a way you can give something without loosing something.

hobolance 也给其他一些中文项目提过该建议,大部分处理是被直接关闭。因为这些项目和 BND、30s 一样都是面向国内用户的,比如 UnblockNeteaseMusic6、CS-Notes7

为什么要用中文

在 2014 年 B3log 开源社区的项目 Wide8 在 Hacker News 上就被外国友人吐槽过代码中使用中文注释9,后来我把这些注释改成英文的了。当时 Wide 的 README 及其主要的文档都是英文的,也算是一个国际化项目了。

今年年初我特意把 Wide 的 README 改成中文的了,因为这几年下来我逐步觉得用中文给项目写文档(包括代码注释)很有意义(这也是为什么要做协慌网10的动机之一):

可能我个人能力有限,无法面面俱到。如果我有时间精力,那肯定是中英双语覆盖文档和代码注释。不过换个角度看,说明项目需要国际化方面的贡献者,这部分工作量交由贡献者来完成也更好一些。开源不只帮助用户,也帮助项目本身,这是相互促进的。

国人开源的现状

这个话题延伸下去会挺悲哀的,本质上是开源精神和现实的冲突。很多开发者或者用户对开源的理解只是停留在免费、安全、情怀这样的层面上,其实远不止这些。这可能也是有些主创直接选择国际化的原因,国内目前还不具备这样的环境。不过我觉得这一切正在改变,因为像我一样的主创也越来越多了。

从主创的角度,我们缺乏的是一片真正的开源土壤,这片土壤绝对不能以商业化盈利为首要目的,否则就会变成一个鸡蛋问题:平台还没做大就想着如何赚开发者的钱(在一些功能细节上设限,在一些产生资金流的地方设限);开源主创们本来就非常艰难了,在这样的平台上做开源简直是难上加难。所以只要以盈利为目的的开源平台都做不好,要做好只有一条路,由大公司注资兜底,不设置盈利目标。

大公司为什么要做这样的投入?因为他们想更好地实现业务整合,以备在更高维度上建立生态系统,最终提升整体竞争力。我们所处的是商业社会,开源这件“存在即合理”的事情也可以看成是商业活动。我感觉中国开源的春天不远了,以开源商业化为商业模式的公司将越来越多,国内的开源浪潮即将成型。

相关链接

  1. BND - 一款图形界面的百度网盘不限速下载器,支持 Windows、Linux 和 Mac
  2. 30s - 前端知识精选集,包含 HTML、CSS、JavaScript、React、Node、安全等方面,每天仅需 30 秒
  3. hobolance - 一个外国友人的 GitHub 账号
  4. English Please - BND
  5. English Please - 30s
  6. UnblockNeteaseMusic - 解锁网易云音乐客户端变灰歌曲
  7. CS-Notes - 技术面试必备基础知识、Leetcode 题解、Java、C++、Python、后端面试、操作系统、计算机网络、系统设计
  8. 一款基于 Web 的 Go 语言 IDE,随时随地玩 golang
  9. A Web IDE for Teams using Golang | Hacker News
  10. 协慌网,一个汉化 Stack Overflow 的网站
  • 开源

    Open Source, Open Mind, Open Sight, Open Future!

    353 引用 • 3283 回帖 • 399 关注
  • 中文
    7 引用 • 87 回帖
1 操作
88250 在 2019-08-19 13:52:56 置顶了该帖
优质回帖
  • InkDP 2 赞同
    捐赠者

    国人可以啃英文,为什么外国友人不能啃啃中文

    为这句话疯狂点赞

  • csfwff 1
    捐赠者

    啃英文啃得我头疼

  • someone756 1 赞同

    中英文无所谓,像我这种大神.

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...
  • kuailexs

    我们都啃英文,外国友人啃啃中文。没毛病

  • 其他回帖
  • 88250
    订阅者 作者

    @suesunss

    专业不专业我觉得和用什么语言来写代码注释关系不大,代码注释也是软件文档的一部分,用中文写代码注释的目的和项目相关文档用中文写是一样的,都是为了让周围的人更好理解。这能保证项目在整体上的一致性,不然文档、社区用户都是中文的,代码注释又用英文就有点尴尬了(现在我这边项目就是这样的情况,所以我想做一些改变)。

    当然,这样做目前来看是“难登大雅之堂”的,也不利于项目在更大范围的传播,也许以后某个阶段到达后会再进行调整和总结吧(也许以后中文更流行了也就不用调整了)。文中最后提到,这个话题延伸下去的话会很悲哀,目前只能叹息我们软件整体产业落后,开源方面也会导致一些冲突。怎么说呢,我觉得一步到位和国际接轨太难了,慢慢发展吧。

    感谢分享交流 😄

    1 回复
  • chengzime

    今天第一次提 PR 就感觉很失望, 吐槽一下 ...
    一个中国人的开源项目, 发现一个 bug, 修改了一下提了一个 PR, 使用中文写的异常详情介绍, 并且在每句中文下面添加了英文翻译, 结果被要求必须删除中文, 全部用英文写, 一度感觉很愤怒 ...
    感觉汉语被侮辱了, 也感觉自己没有被尊重 ...
    只能默默留下了没有技术的眼泪 ...

    只能默默为 D 佬点个大大的赞

    2 回复
  • someone48938 1
    捐赠者

    写英文主要是因为英文写着更顺手,因为我从一开始学习 CS 相关技术就是看的全英文材料,很多名词都不知道中文翻译过来叫什么,如果硬要写中文不是不可以,但是会消耗较多时间,而且看上去可能会显得翻译腔太重。

    最主要的问题是我需要我的文档被更多的人看懂。英文的普及度很高了,基本上任何一个国家,搞技术的人或多或少都会懂一些英文。而中文在国外非华裔群体里的普及度是相当的低。设身处地的考虑,假设我看到一个项目的 README 或者 wiki 全是德文、俄文之类我不认识的文字,Google 翻译一下又狗屁不通(这很常见,目前机翻对于技术相关文章的局限性还是普遍存在的),我一定不会继续看下去。这样下来,不利于项目更好地为大众所用,也不是很符合开源软件或者自由软件的精神。因此,我的项目一般都会用英文写文档和注释,博客也用英文来写。localization 的事情,还是留给其他贡献者。

    当然有一个例外,就是当这个项目面向的群体是国人时。比如在公司做的项目,用户和与我合作开发的同事都是中国人,那我会选择用中文来写文档,注释也尽量用中文。对于开源项目而言也同理,如果面向的用户群体以国人为主(比如我要做一个黑客派的客户端,而黑客派是一个中文社区,几乎没有见到外国友人的访问),且他们不一定具有相关技术背景的话,那我会考虑使用中文来写文档,或者在英文文档之外提供精心翻译后的中文文档。

  • 查看全部回帖