战码前锋，PR征集令（以下简称“战码前锋”）第二期正如火如荼地进行中，触及OpenAtom OpenHarmony（以下简称“OpenHarmony”）主干仓、SIG仓、三方库，共计1000+代码仓任君挑战。
刚看到活动的朋友们肯定有个疑问：什么样业务背景的人能参加战码前锋活动？是否能够找到提PR的一些基本方法？为此，咱们邀请了战码前锋第一期的奉献者，也是第二期队长之一的King He为咱们带来了他的一些有用经历。以下是他的共享。
实践证明，来自不同背景的人，有助于充沛发现问题。假如你是一名翻译，尽管不一定有深沉的技能功底，但你能够发挥专业才干，帮助咱们发现项目中言语类问题。同理，测验、材料、法务背景的同事亦是如此，不同特长的人参加，更有利于充沛地发现各种类型的问题。这点类似灵敏开发的全功用团队。参加人物更全面，发现问题更充沛。英豪不问出处，只需勇于挑战，均可参加战码前锋，为开源项目添砖加瓦。
本文是依据一名技能笔译的视角，从开发者体会的角度和咱们一同讨论代码文件中的常见材料类问题，并在此根底上共享一些个人的建议。文章主要分为三个部分：材料内容关于开发者生态的意义；影响材料体会的典型问题；提高材料体会的一些建议。
首要，需求简略了解一下材料内容关于开发者生态的意义。
依据近几年的开发者生态现状和开源生态陈说，完善、精确的内容，是开发者选择一个生态的重要因素之一。依据Accenture的调查陈说显现，开发者认为技能精确及最新的内容（technically accurate and up-to-date content）是开发者生态中最为重要的两个要素。
OSCHINA和Gitee联合发布的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成为万物互联时代的明珠。
若干年后，当咱们回忆起这段历史，咱们能够对着开源奉献者证书，骄傲地对着咱们的孩子说，这巨大的生态背面有着咱们的一份努力和支付，这多么的让人引以为傲。
