战码先锋，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成为万物互联时代的明珠。
若干年后，当咱们回顾起这段历史，咱们能够对着开源贡献者证书，骄傲地对着咱们的孩子说，这平凡的生态背地有着咱们的一份致力和付出，这如许的让人引以为傲。