0
  • 聊天消息
  • 系统消息
  • 评论与回复
登录后你可以
  • 下载海量资料
  • 学习在线课程
  • 观看技术视频
  • 写文章/发帖/加入社区
会员中心
创作中心

完善资料让更多小伙伴认识你,还能领取20积分哦,立即完善>

3天内不再提示

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

OpenAtom OpenHarmony 来源:OpenAtom OpenHarmony 作者:OpenAtom OpenHarmony 2022-09-02 10:50 次阅读

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

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

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

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

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

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

505f2160-29f7-11ed-ba43-dac502259ad0.png

来源:ENGAGING THE DEVELOPER COMMUNITY - What Developer Ecosystems Need to Know,Accenture

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

50e8cc58-29f7-11ed-ba43-dac502259ad0.png

--摘自《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。

52b9875c-29f7-11ed-ba43-dac502259ad0.png

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

52d79d5a-29f7-11ed-ba43-dac502259ad0.png

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

52f05e26-29f7-11ed-ba43-dac502259ad0.png

二、内容完整

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

53212d80-29f7-11ed-ba43-dac502259ad0.png

三、组织合理

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

5357665c-29f7-11ed-ba43-dac502259ad0.png

参考修改如下:

53821140-29f7-11ed-ba43-dac502259ad0.png

四、一致性

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

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

53a0559c-29f7-11ed-ba43-dac502259ad0.png

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

53c1a896-29f7-11ed-ba43-dac502259ad0.png

五、基础语言问题

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

54e8428e-29f7-11ed-ba43-dac502259ad0.png

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

551d7ce2-29f7-11ed-ba43-dac502259ad0.png

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

553626f2-29f7-11ed-ba43-dac502259ad0.png

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

5550ec4e-29f7-11ed-ba43-dac502259ad0.png

六、版式问题

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

557ff804-29f7-11ed-ba43-dac502259ad0.png

修改如下:

559976d0-29f7-11ed-ba43-dac502259ad0.png

七、包容性

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

55abd35c-29f7-11ed-ba43-dac502259ad0.png

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

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

提升资料体验的一些倡议

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

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

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

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

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

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

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

审核编辑:彭静
声明:本文内容及配图由入驻作者撰写或者入驻合作网站授权转载。文章观点仅代表作者本人,不代表电子发烧友网立场。文章及其配图仅供工程师学习之用,如有内容侵权或者其他违规问题,请联系本站处理。 举报投诉
  • 文件
    +关注

    关注

    1

    文章

    565

    浏览量

    24733
  • 代码
    +关注

    关注

    30

    文章

    4780

    浏览量

    68541
  • 开发者
    +关注

    关注

    1

    文章

    569

    浏览量

    17007

原文标题:资深技术笔译总结的这7条建议,看完提PR效率倍增

文章出处:【微信号:gh_e4f28cfa3159,微信公众号:OpenAtom OpenHarmony】欢迎添加关注!文章转载请注明出处。

收藏 人收藏

    评论

    相关推荐

    资深技术笔译总结的这7条建议,看完提PR效率倍增

    。本文是基于一名技术笔译的视角,从开发者体验的角度和大家一起探讨代码文件常见资料问题,并在
    发表于 09-07 10:31

    实现网页播放FLV文件的源代码

    实现网页播放FLV文件的源代码 使用方法:方法一、js嵌入直接copy下面代码,修改其中红色部分,即:swf_width、swf_height、texts、files 参数
    发表于 02-09 15:30 22次下载

    基于关键判定的代码提交理解辅助方法

    软件代码提交是最重要的软件版本演化数据之一,被广泛应用于软件审查和软件理解.对于程序员,提交的理解难度随着受影响的数量、修改的代码量的增加而增加.通过对大量数据的分析发现:识别出提
    发表于 12-28 16:38 0次下载

    电阻pcb部分库文件免费下载

    资料中含有电阻pcb部分库文件,可免费下载
    发表于 06-10 08:00 0次下载

    常见文件扩展名及详细资料说明

    A 对象代码文件 AAM Authorware shocked 文件 AAS Authorware shocked 包 ABF Adobe 二进制屏幕字体 ABK CorelDRAW 自动备份
    发表于 06-06 16:52 0次下载

    数字电压表的设计资料和源代码程序及工程文件免费下载

    本文档的主要内容详细介绍的是数字电压表的设计资料和源代码程序及工程文件免费下载。
    发表于 12-24 17:22 52次下载
    数字电压表的设计<b class='flag-5'>资料</b>和源<b class='flag-5'>代码</b>程序及工程<b class='flag-5'>文件</b>免费下载

    C语言的源代码文件和目标文件与可执行文件的详细介绍

    1、源代码文件 存放程序代码文件,即我们编辑代码文件,称为源
    的头像 发表于 02-18 11:52 8631次阅读

    使用文件保存游戏的python代码资料说明

    本文档的主要内容详细介绍的是使用文件保存游戏的python代码资料说明免费下载。
    发表于 09-24 17:08 11次下载
    使用<b class='flag-5'>文件</b>保存游戏的python<b class='flag-5'>代码</b>和<b class='flag-5'>资料</b>说明

    PCB设计十大常见的问题资料下载

    电子发烧友网为你提供PCB设计十大常见的问题资料下载的电子资料下载,更有其他相关的电路图、源代码、课件教程、中文
    发表于 04-01 08:49 21次下载
    PCB设计<b class='flag-5'>中</b>十大<b class='flag-5'>常见</b>的问题<b class='flag-5'>资料</b>下载

    电路电容的常见使用资料下载

    电子发烧友网为你提供电路电容的常见使用资料下载的电子资料下载,更有其他相关的电路图、源代码、课件教程、中文
    发表于 04-10 08:49 12次下载
    电路<b class='flag-5'>中</b>电容的<b class='flag-5'>常见</b>使用<b class='flag-5'>资料</b>下载

    常见的物联网通信方式资料下载

    电子发烧友网为你提供四常见的物联网通信方式资料下载的电子资料下载,更有其他相关的电路图、源代码、课件教程、中文
    发表于 04-19 08:55 5次下载
    四<b class='flag-5'>类</b><b class='flag-5'>常见</b>的物联网通信方式<b class='flag-5'>资料</b>下载

    鸿蒙应用的几种常见类型的文件

    应用的几种常见类型的文件 ①Ability Ability 是应用所具备的能力的抽象,一个应用可以包含一个或多个 Ability。 Ability 分为两种类型:FA(Feature
    的头像 发表于 08-20 10:06 6009次阅读
    鸿蒙应用<b class='flag-5'>中</b>的几种<b class='flag-5'>常见</b>类型的<b class='flag-5'>文件</b>

    基于JAVA的RSA文件加密软件的设计与实现(源代码及论文)

    ,并在32位windows平台封装成组件。在.Net平台引用此组件,实现可以对任意文件进行RSA加密操作的窗体应用程序。经过加密的文件以及密钥文件都是文本文件。给出关键
    发表于 06-09 16:01 0次下载

    隔离实现之自定义加载器的扩展

    机制。 2、加载是什么? 加载是一种过程,是将class文件加载到jvm内存的过程。当代码逻辑需要引用
    的头像 发表于 10-08 15:17 635次阅读

    hex文件如何查看原c语言代码

    是处理器可以直接执行的指令,而 C 语言代码则是人类可读的高级编程语言代码。 然而,如果你想要从 .hex 文件获取一些有用的信息或者对程序进行分析,你可以考虑以下几种方法: 反汇编
    的头像 发表于 09-02 10:37 2152次阅读