王莉:将开发文档英文化和本地化,努力让OpenHarmony走向全球 原创
编者按:在 OpenHarmony 生态发展过程中,涌现了大批优秀的代码贡献者,本专题旨在表彰贡献、分享经验,文中内容来自嘉宾访谈,不代表 OpenHarmony 工作委员会观点。
王莉
华为技术有限公司
翻译及本地化工程师
对于开源项目及其开发者而言,一份书写规范、质量上乘、及时更新的开发者文档是至关重要的——它能帮助开发者快速入门,检视代码逻辑,提升开发效率,从而吸引更多开发者加入,繁荣开源生态。
作为由开放原子开源基金会孵化及运营的开源项目,OpenAtom OpenHarmony(以下简称“OpenHarmony”)在诞生初期也曾面临开发者文档太少、质量不够高等窘境。经过 OpenHarmony 工作委员会、各家共建单位的开发者们一年多的努力,我们很欣喜地看到开发者文档一点点变得丰富,系统能力不断构建,代码也在不断完善。
华为翻译及本地化工程师王莉,正是这些参与文档共建的开发者中的一员。
在近期 OpenHarmony PMC(Project Management Committee 项目管理委员会)举行的 2022 年 2 月份代码贡献者评选中,王莉因为在开发者文档领域的突出贡献,成功被评为“代码贡献月度之星”,成为代码贡献 Top10 的两位女性开发者之一。
王莉和她所在的团队,主要贡献点在于社区的英文化和本地化。加入 OpenHarmony 项目后,他们和资料团队一起学习和研究了业界主流的 SIG,组建了自己的 SIG docs;制定了社区行为准则、贡献流程、优化问题反馈和处理机制;制定了代码规范和写作模板,植入了 CI 门禁工具、自动提交翻译 Issue 的 bot,并输出了 OpenHarmony 各个子系统的相关指导文档,帮助开发者们更加轻松、愉快地使用 OpenHarmony。
本期 OpenHarmony 开发者故事,我们与王莉一起聊了她和她所在的团队、参与 OpenHarmony 项目的初心、代码贡献如此突出的心得、SIG docs 运营过程中的趣事,以及开源过程中遇到的技术难题、对 OpenHarmony 未来的期待等话题。现将专访内容整理如下,希望对你有所启发。
Q=OpenHarmony A=王莉
Q1:请简要介绍下自己,以及所在开发团队
大家好,我是来自华为的王莉,是一名翻译及本地化工程师,目前主要从事 OpenHarmony 相关文档的翻译及本地化工作。目前我们团队主要活跃在 SIG docs,负责 OpenHarmony 项目所有文档的中到英翻译工作,常见的比如 API 参考、readme、操作指导等翻译,外籍输出件的 PR,以及输出相关的本地化贡献指导、规范和 FAQ。
此外,我们还携手近 10 名资料工程师以及数百位开发工程师,结对优化中文资料。希望能够通过我们的工作,让更多的开发者高效地了解和使用 OpenHarmony。
Q2:作为一名翻译及本地化工程师,您最初为什么会选择加入OpenHarmony生态、参与开源共建呢?您认为,OpenHarmony项目最吸引人的点在哪里?
我在加入 OpenHarmony 项目之前,曾经做过计算的产品,从我对口的产品一开始清一色的 Intel 处理器,到我们自己的鲲鹏和昇腾处理器,再到生机勃勃的鲲鹏生态、方兴未艾的 OpenHarmony 生态……一路走来,我们清楚地知道 OpenHarmony 项目的重要性,更明白开源的重大意义。
OpenHarmony 是一项伟大的事业,我能通过自己的专业能力为社区贡献一份力,这让我觉得这个工作是非常有价值的。
Q3:这次您被OpenHarmony PMC委员会推举为“代码贡献月度之星”,意味着您对OpenHarmony项目的贡献已经属于业界顶尖水平,十分了不起!加入OpenHarmony这么短的时间却达成了这样好的效果,请问您的“秘诀”是什么?您是否方便从业务角度具体介绍一下,怎么才能让开发者更加满意,把开源共建做得更好呢?
我和我所在的团队,对社区的主要贡献点在于社区的英文化和本地化,与代码贡献者还是有所区别的。所以能在 OpenHarmony 这次评选中获得“代码贡献月度之星”,我其实觉得十分意外,同时又倍受鼓舞。
一开始加入项目组,我感觉挑战还是挺大的。虽然我是一名语言工作者,但并不熟悉开发语言;对于 OpenHarmony 所涉及的众多子系统和技术,也觉得 gap 很大;对于 SIG docs 的运作也一无所知……
好在兴趣是最好的老师,缺什么就补什么,这个过程必定是先苦然后慢慢一点一点地甜。作为开发者文档最认真的读者,我们必须要理解文档的每一话。同时,作为最初的体验者,我们也能站在读者的角度上,发现一些问题,对文档提出一些优化建议。对于 SIG 的运作,我们的小团队也和资料团队一起,在不断地探索和改进……
我们的目标,从小了说是让资料好用、易用、开发者喜欢用,从大了说是提供一个知识、能力分享的平台,点亮更多开发者。这一目标的达成,也和开源生态的建设一样,需要大家一起贡献自己的智慧和力量。
Q4:您和您的团队小伙伴,在参与OpenHarmony项目贡献的过程中,一定有一些刻骨铭心/印象深刻的经历,比如组建和参与SIG docs运营之类。可以给我们分享一下吗?
我之前完全没有接触过开源项目,对于开源的理解也仅限于字面意思。
在加入到 OpenHarmony 这个项目以后,我们团队和资料团队都在这方面下了很多工夫。我们学习和研究了业界主流的 SIG,组建了自己的 SIG docs;制定了社区行为准则、贡献流程、优化问题反馈和处理机制;制定了代码规范和写作模板,植入了 CI 门禁工具、自动提交翻译 Issue 的 bot,并输出了 OpenHarmony 各个子系统的相关指导文档。目前,SIG docs 已成为 OpenHarmony 社区最活跃的 SIG 之一,关注量和 Fork 数量都遥遥领先。
与以前翻译工作不同的是,我们需要在 Gitee 上处理文档,为此我们专门学习了 markdown 语法、Gitee 的常见操作命令等。
一开始由于不了解 Gitee 文档的运作机制,感觉整个操作流程很是复杂;在提交 PR 的时候,也遇到过各种问题,最初的时候,经常有挫败感。
在不断的试错过程中,我们把工作中的经验和教训都记录下来,形成了我们的《开源项目翻译操作指导书》,这样可以固化下来的东西就成了我们的操作规范,也方便更多的爱好者可以很快地上手为社区做贡献。
Q5:在整个开发进程中,您和您的团队遇到过哪些技术上或其他方面的难题?这些难题又是如何被逐一解决的?在这些难题被解决的过程中,您总结了哪些宝贵的经验or教训?
我们的合作伙伴,是十多位资料同事和上百位来自不同团队甚至是不同公司的开发同事,如何在社区提供高质量的文档真的不是一件容易的事。
举一个很小的例子来说,仅是文档中的图形就可能有各种颜色和风格。为了帮助众多的开发者撰写合格的文档,我们的资料团队组织了社区写作赋能线上课程、推广社区写作模板和规范;我们也和资料团队一起,参与原稿案例推广和宣传。
针对社区文档类型多,格式比较乱的问题,资料团队有计划地对文档进行纯净 markdown 格式转换。一开始在 Gitee 提交文档和翻译的时间比较长,闭环率较低。通过各种数据辅助分析,我们也想了很多办法,比如有效地识别同一文档的 Issue 合并处理,提升处理效率和闭环率。
生态的繁荣离不开广大生态伙伴、每一位开发者的共同努力,每一个 Issue、PR 都是构建生态繁荣的养分。所以我们的小目标,就是要把这一砖一瓦搭建好。
Q6:加入OpenHarmony生态以来,您最大的惊喜是什么?或者有哪些具体的收获?
加入 OpenHarmony 生态以后,最大的惊喜是开阔了眼界,学习到了更多的知识。
传统的文档反馈机制,是通过官网在线反馈文档问题、等待文档工程师确认,再周期性更新发布。基于 Gitee 的开放式讨论和 Issue 反馈机制,使文档更新更及时。
我们最大的收获就是,依托 SIG docs 为 OpenHarmony 提供翻译和本地化服务,提供了更为丰富的文档和更为有效的反馈和处理机制,帮助全球开发者更加轻松、愉快地使用 OpenHarmony。我相信后续我们还可以更多地利用工具来提升一些效率,SIG docs 会越来越好。
Q7:您期待未来OpenHarmony哪些方面能够得到改善、提供更多支持?
作为一名文档工作者 & 技术小白,我的关注点可能更多还是在资料方面。
我希望我们的资料可以根据不同的读者进行分层,比如小白级(可以提供一些科普文档,类似深圳卫健委公众号那样的)、初级开发者、高级开发者;入口清晰,更为体系化。
我们整个体系的术语,感觉还可以再完善再清晰一些。很多时候,术语就像一条链接各个子系统的脉络;如果术语这个脉络做得好,会非常方便初学者上手。同时,如果能有更多动手体验方面的尝试,就再好不过了。
我们衷心希望 OpenHarmony 能吸引到更多的开发者,后续我们能有机会提供更多语种的服务。
Q8:OpenHarmony目前仍处在开发探索阶段,很多共建单位和生态伙伴还不清楚开源项目的玩法,或不知该如何着手进行开发。可以请您给大家分享一条,您认为最值得分享的心得,或最想说的一句话吗?
我最想说的是,Do it 永远比 Say it 更重要。欢迎大家一起来开源共建,OpenHarmony 是一个开放、共享的大舞台,加入我们,你也有机会成为闪耀的代码贡献之星!
Q9:请问您还有什么话想告诉大家?
我非常幸运能从事我喜欢的工作,更是非常非常地幸运能够加入 OpenHarmony 项目,能在这种大环境背景下,贡献自己的微薄之力,我觉得是我平凡的职业生涯中很幸福的一件事。
从 2020 年到 2021 年,我见证并参与了 OpenHarmony 的成长,也对未来充满希望。我希望能有更多的开发者加入我们,一起为 OpenHarmony 做出自己的贡献。