战码先锋,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成为万物互联时代的明珠。

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

资深技术笔译总结的这7条建议,看完提PR效率倍增的更多相关文章

  1. 将Web应用性能提高十倍的10条建议

    导读 提高 web 应用的性能从来没有比现在更重要过.网络经济的比重一直在增长:全球经济超过 5% 的价值是在因特网上产生的(数据参见下面的资料).这个时刻在线的超连接世界意味着用户对其的期望值也处于 ...

  2. <转>“人脉投资”的10条建议

    谁都知道人脉很重要,所以有些人非常勤奋的“做人脉”,他们往往会这样做—— 积极的参与各类线下活动,逢人就换名片.加微信. 见到名人或者重要人物必合影,而且他们还会掏出手机来给你看. 逢年过节,给所有他 ...

  3. C++编程开发学习的50条建议(转)

    每个从事C++开发的朋友相信都能给后来者一些建议,但是真正为此进行大致总结的很少.本文就给出了网上流传的对C++编程开发学习的50条建议,总结的还是相当不错的,编程学习者(不仅限于C++学习者)如果真 ...

  4. 关于PHP开发的9条建议

    这篇文章主要介绍了关于PHP开发的9条建议,都是个人的一些经验总结,有需要的小伙伴可以参考下. 本文只是个人从实际开发经验中总结的一些东西,并不是什么名言警句,写出来有两个目的:一是时刻提醒自己要按照 ...

  5. 将 Web 应用性能提高十倍的10条建议

    提高 web 应用的性能从来没有比现在更重要过.网络经济的比重一直在增长:全球经济超过 5% 的价值是在因特网上产生的(数据参见下面的资料).这个时刻在线的超连接世界意味着用户对其的期望值也处于历史上 ...

  6. 从零开始学 iOS 开发的15条建议

    事情困难是事实,再困难的事还是要每天努力去做是更大的事实. 因为我是一路自学过来的,并且公认没什么天赋的前提下,进步得不算太慢,所以有很多打算从零开始的朋友会问我,该怎么学iOS开发.跟粉丝群的朋友交 ...

  7. 学习javascript怎么入门,初学者5条建议

    你是否已经初步掌握了html和css,但完全不知道从何入手Java?如果是,这里总结了5条建议,帮助JavaScript初学者总结学习方法,提高学习效率. 一.多看视频少看书 对初学者而言,看书的效率 ...

  8. IOS开发-提升app性能的25条建议和技巧

    前言 这篇文章介绍了作者开发工作中总结的25个iOS开发tips, 多年之前读过这篇文章.收益良多,基本每一个tips在我的应用开发过程中都使用过.今天把这篇文章又一次整理转发下,与大家一起学习,不论 ...

  9. 关于Java代码优化的44条建议!

    关于Java代码优化的N条建议! 本文是作者:五月的仓颉 结合自己的工作和平时学习的体验重新谈一下为什么要进行代码优化.在修改之前,作者的说法是这样的: 就像鲸鱼吃虾米一样,也许吃一个两个虾米对于鲸鱼 ...

  10. 提高Axure设计效率的10条建议

    http://www.woshipm.com/ucd/92153.html Axure 是创建软件原型的快速有力的工具.上手很容易,但是,其中存在一个危险.这款软件是如此的直观以至于很多用户可以在没有 ...

随机推荐

  1. 关于json序列化时报错json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

    1.今天在写客户端与服务端交互的程序的时候,发现了一个问题 客户端代码 #客户端程序主要是发送注册请求/登录请求给服务端,服务端接收响应后回应对应的应答给客户端,客户端接收响应后,然后做一些操作 # ...

  2. django学习第六天---shell指令,单表基于双下划线的模糊查询,distinct注意点,字段的choices属性,url反向解析,orm多表操作创建表

    shell指令 命令 python manage.py shell 在Terminal,执行上面这个指令会进入到python解释器环境中,并且加载了我们当前django项目配置环境,所以可以在当前sh ...

  3. centos8.x阿里源配置

    >>> cd /etc/yum.repo.d >>> mkdir bak >>> mv *.repo bak/ >>> cd b ...

  4. pwd模块

    # pwd模块提供了获取UNIX平台用户的账户与密码信息(通过文件/etc/passwd),在所有的UNIX版本平台都可以用. # pwd模块返回的是一个类似元组的对象,该对象的各个属性对应于pass ...

  5. MindSponge分子动力学模拟——使用MDAnalysis工具进行后分析(2024.02)

    技术背景 分子动力学模拟(Molecule Dynamics Simulation,MD),本质上是一门采样技术.通过配置力场参数.拓扑结构和积分器,对一个给定的体系不断的采样,最终得到一系列的轨迹. ...

  6. 【Azure Fabric Service】Service Fabric 遇见错误信息记录 - The process/container terminated with exit code:2148734499

    问题描述 Service Fabric 在升级 Application 过程中,发布了新的代码后,启动应用中遇见了如下错误: Error message: System.Hosting' report ...

  7. Task Manager 的设计简述

    讲解 Task Manager 之前,在这里先介绍一些 Task Manager 会使用到的概念术语. 图数据库 Nebula Graph 中,存在一些长期在后台运行的任务,我们称之为 Job.存储层 ...

  8. 如何扩展Spark Catalyst,抓取spark sql 语句,通过listenerBus发送sql event以及编写自定义的Spark SQL引擎

    1.Spark Catalyst扩展点 Spark catalyst的扩展点在SPARK-18127中被引入,Spark用户可以在SQL处理的各个阶段扩展自定义实现,非常强大高效,是SparkSQL的 ...

  9. redis迁移同步工具-redis-shake

    官方文档: https://github.com/alibaba/RedisShake/wiki/快速开始:数据迁移 下载: https://github.com/alibaba/RedisShake ...

  10. 将MindSpore运行结果输出到log文件

    技术背景 我们在Linux系统下使用一些深度学习框架(如MindSpore)运行脚本的时候,经常会用一些打印输出来判断当前执行的步骤,或者是使用打印输出来定位算法问题.但是在Linux系统下程序输出其 ...