代码文件中的常见资料类问题

战码先锋，PR征集令（以下简称“战码先锋”）第二期正如火如荼地进行中，涉及OpenAtom OpenHarmony（以下简称“OpenHarmony”）主干仓、SIG仓、三方库，共计1000+代码仓任君挑战。

刚看到活动的朋友们肯定有个疑问：什么样业务背景的人能参与战码先锋活动？是否可以找到提PR的一些基本方法？为此，我们邀请了战码先锋第一期的贡献者，也是第二期队长之一的King He为我们带来了他的一些有效经验。以下是他的分享。

实践证明，来自不同背景的人，有助于充分发现问题。如果你是一名翻译，虽然不一定有深厚的技术功底，但你可以发挥专业能力，帮助大家发现项目中语言类问题。同理，测试、资料、法务背景的同事亦是如此，不同专长的人加入，更有利于充分地发现各种类型的问题。这点类似敏捷开发的全功能团队。参与角色更全面，发现问题更充分。英雄不问出处，只要敢于挑战，均可参与战码先锋，为开源项目添砖加瓦。

本文是基于一名技术笔译的视角，从开发者体验的角度和大家一起探讨代码文件中的常见资料类问题，并在此基础上分享一些个人的建议。文章主要分为三个部分：资料内容对于开发者生态的意义；影响资料体验的典型问题；提升资料体验的一些倡议。

首先，需要简单了解一下资料内容对于开发者生态的意义。

根据近几年的开发者生态现状和开源生态报告，完善、准确的内容，是开发者选择一个生态的重要因素之一。根据Accenture的调查报告显示，开发者认为技术准确及最新的内容（technically accurate and up-to-date content）是开发者生态中最为重要的两个要素。

来源：ENGAGING THE DEVELOPER COMMUNITY - What Developer Ecosystems Need to Know，Accenture

OSCHINA和Gitee联合发布的2021中国开源开发者报告，进一步佐证了这一点。从报告可以看出，相关文档/资料是否丰富的重要性仅次于源码质量。

-－摘自《2021中国开源开发者报告》

好的资料胜过千军万马，资料的重要性不言而喻。好马配好鞍，好的代码要有好的资料配套，才能产生1+1大于2的效果，才能帮助开发者更好地上手，产生良好的开发者体验，吸引更多的开发者参与。一个复杂的技术产品，如果没有说明书，用户就没法高效、正确地使用该产品。代码就好比复杂的产品，没有完备的资料，开发者将无法理解源码的作用和实现机制，在极大程度上影响其体验。

对于OpenHarmony开源项目，文本内容主要包含两个部分：一是Docs仓中发布的文档，包括但不限于开发指南、API参考等。二是代码仓中包含的各种描述性信息，如readme、代码注释、log日志、API说明等。

那么，影响开发者体验资料内容质量要素有哪些呢？

根据开发者生态相关报告，这些要素包括但不限于：accuracy（准确性）、completeness（完整性）、currency（时近性）、findability（检索性）及readability（易读性）。需要注意的是，此前的报告大多以主流开源项目作为基础研究对象。这些项目主要由欧美Top玩家主导，在语言文化方面有着天然优势，具备良好的国际化和本地化成熟度。因此，国际化、本地化、基础语言质量等方面同样需要OpenHarmony开源项目重点关注。

接下来，我们将针对英文文本内容，在战码先锋活动中可关注哪些方面的典型问题？本次主要以非Docs仓的文本问题作为示例。

特别声明：以下示例仅作为技术交流的示意用途，不构成任何明示或暗示的声明、陈述。同时，由于相关仓内容在持续的变化更新，如有出入，请以实际为准。

一、准确清晰

示例1：辞不达意。这里API是DelUser，其功能为删除用户，因此描述应该是Delete a user而非user authentication。

示例2：意思错误。PIN_MIXED是Mixed PIN鉴权，FACE_2D才是2D人脸识别鉴权。

示例3：含义相反。这里是inactive状态的回调，叠加语法错误，增加理解难度。实际含义应为：Callback invoked in the main thread when an ability becomes inactive.

二、内容完整

根据开源要求，开源代码仓中注释内容均需英文化。受限于英文表达能力或内部合规方面的考量，开发人员可能会倾向于删除或者放弃提供一些需要英文化的必要内容，如文件的简述、实现机制或者注意等，如下例所示：左侧enum缺少必要的注释，开发者无法理解short period、normal period和long period的差异。

三、组织合理

信息的组织应符合用户的逻辑认知顺序，例如，API介绍应遵循“API功能说明+权限+参数说明+返回说明”的信息组织结构。下面例子中，API名称被直接替代为API功能说明，而实际的API功能说明则出现在permission之后。

参考修改如下：

四、一致性

一致性主要体现在风格的一致性和内容的一致性两方面。

示例1：表达风格不一致。如下日志描述中，上下两行的大小写风格不一致：

示例2：内容和实际不符。如下Readme中，目录结构中代码仓名称和实际代码仓名称不符：

五、基础语言问题

示例1：拼写错误出现在注释语句或API名称、参数等，如下例所示：faild拼写错误，正确应该为failed。

再看一个特例，这里pin虽然并非拼写错误，但是实际上它是personal identification number的缩写PIN，如写成pin，表达的意思就完全不一样了。

示例2：语法错误、表达不规范等问题在代码文件中普遍存在，如下例所示：上下两个句子风格不一致。start device find for restart没有使用sentence caps，第一个单词首字母大写。两个句子均存在语法错误，而且因为用词不当问题，两个句子之间的内在逻辑关联没有体现，前面表示动作：Start discovery of devices for restart.后面则表示动作结果：Failed to start device discovery.

再来看一个示例，此处Active和Deactive为形容词，不能代替动词使用，对应动词应该是Activate和Deactivate。

六、版式问题

单行内容超宽，或者断行不当等问题会造成版式不美观。如下例所示，该句子被不当断行，下面一行内容可移到上面一行：

修改如下：

七、包容性

包容性语言是当今的一个重要趋势，使用无偏见、包容性的措辞是品牌温度在文化遵从和人文关怀方面的重要体现。一些原被接受认可的术语被逐步取代，如chairman、aldermen暗示男性的统治力，尤其是在对女性致辞/讲话时。如下示例表达违反了包容性语言中角色和标签的要求，应该使用parent替代father：

还有一些值得我们关注的方面，如慎用定义阶层、种族的术语。例如，当前行业和友商的做法是尽量用primary及secondary分别替换master和slave，用trustlist和blocklist分别替换blacklist及whitelist等。

以上是一些影响语言文化体验的问题示例，我们在战码活动中可对此种类型的问题多加关注。

提升资料体验的一些倡议

一个成功的生态离不开极致的开发者体验。错误无论大小，都会给开发者体验带来不同程度的负面影响。借此机会，呼吁大家：

• 转变观念：开发者资料是开发者旅程（developer journey）中的关键一环，对开发者体验起着不可忽视的重要作用。对于开源项目，高质量的资料更是开发者参与贡献的基础。产品功能和资料如天平的两端，应被赋予同样的重视。

• 用户视角：开发者是资料的第一读者和用户。在战码活动中，我们可基于开发者的视角去发现影响开发者完成任务的准确性、完整性、清晰性等各方面问题，积极去提Issue、PR，共同提升资料质量。

• 低错清零：一些低级错误不一定会阻碍用户理解并完成任务，但可以确定的是会对品牌的声誉带来负面影响。我们应尽量去发现并修改此类问题，共同捍卫OpenHarmony的质量口碑。

欢迎感兴趣的开发者朋友们一起参与战码先锋，PR征集令！在Gitee的OpenHarmony代码仓提交PR参与活动，和全球的开发者一起共建OpenHarmony的繁荣生态！现在就打开Gitee，为OpenHarmony提PR，你的一小步，就是OpenHarmony开源的一大步。

我们一群人在一起做一件伟大的事情，唯有共同携手，在各自专长的领域去构筑极致的开发者体验，方能助力OpenHarmony生态行稳致远，也必将共同见证OpenHarmony成为万物互联时代的明珠。

若干年后，当我们回顾起这段历史，我们可以对着开源贡献者证书，自豪地对着我们的孩子说，这伟大的生态背后有着我们的一份努力和付出，这多么的让人引以为傲。　　

      审核编辑：彭静