根据近几年的开发者生态现状和开源生态报告，完善、准确的内容，是开发者选择一个生态的重要要素之一。

 根据Accenture的调查报告显示，开发者认为技术准确及最新的内容（technically accurate and up-to-date content）是开发者生态中最为重要的两个要素。

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

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

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

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

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

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

为了便于大家理解，下面我们一起来看一些简单示例。

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

 一、准确清晰

示例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，第一个单词首字母大写。两个句子均存在语法错误，而且两个句子之间的逻辑关联没有体现，前面表示重启发现的设备，第二个表示重启失败。正确表达应该是：Restart the device discovered.和Failed to restart the device./Restarting the device failed.

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

六、版式问题

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

修改如下：

七、包容性

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

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

 结语

生态的成功离不开极致的开发者体验，而极致的开发者体验离不开良好的语言文化体验。让我们共同关注语言文化体验，一起去构筑极致的开发者体验，方能助力开源生态行稳致远。