登录 注册

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

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

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!

    408 引用 • 3574 回帖
  • 中文
    6 引用 • 89 回帖
1 操作
88250 在 2019-08-19 13:52:56 置顶了该帖
昆明 位置
5 感谢
16 关注
2 收藏
9 赞同
1 操作
65 回帖
2
16.2k 707 2.4k 2.3k 5 3.5k 1.1k 14 1.3k 4.7k

相关帖子

优质回帖
  • InkDP • • 2 赞同
    捐赠者

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

    为这句话疯狂点赞

  • csfwff • • 1
    捐赠者

    啃英文啃得我头疼

  • someone756 • • 1 赞同

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

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

欢迎来到这里！

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

注册 关于
请输入回帖内容 ...
  • someone756 • • 1 赞同

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

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

    @suesunss

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

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

    感谢分享交流 😄

    1 回复
  • someone48938 • • 1
    捐赠者

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

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

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

  • suesunss • • 1

    说的是太绝对了，但是也提到了，我们的开源环境有一定的问题。我也跟欧洲的开发者接触过，他们也有很多优秀的项目，但是他们很多并不是上来就用自己的母语去写代码注释，这样肯定是不利于项目走出去的。并不是说我们的项目中不能用中文，但是使用英语有几点好处：

    1. 计算机科学毕竟欧美发展的历史要领先我们，很多词汇、表达用英语表达更能够方便开源社区去理解。
    2. 编程语言本身是英文的，如果函数名、变量名、注释都是各国母语，这样的项目到时候如果要推广出去好改吗？
    3. 开源社区需要有自己的交流语言、习惯与惯例，然后用这种『共同性』去交流，比如代码，比如注释，话说回来，如果真的是好东西，我们请社区中的活跃者去翻译成自己地语言，这样的路径不是更好吗？
  • 查看全部回帖
88250
但行好事莫问前程 昆明
回帖
33773
 帖子
712
 积分
167971