戰(zhàn)碼先鋒,PR征集令(以下簡稱“戰(zhàn)碼先鋒”)第二期正如火如荼地進行中,涉及OpenAtom OpenHarmony(以下簡稱“OpenHarmony”)主干倉、SIG倉、三方庫,共計1000+代碼倉任君挑戰(zhàn)。
剛看到活動的朋友們肯定有個疑問:什么樣業(yè)務(wù)背景的人能參與戰(zhàn)碼先鋒活動?是否可以找到提PR的一些基本方法?為此,我們邀請了戰(zhàn)碼先鋒第一期的貢獻者,也是第二期隊長之一的King He為我們帶來了他的一些有效經(jīng)驗。以下是他的分享。
實踐證明,來自不同背景的人,有助于充分發(fā)現(xiàn)問題。如果你是一名翻譯,雖然不一定有深厚的技術(shù)功底,但你可以發(fā)揮專業(yè)能力,幫助大家發(fā)現(xiàn)項目中語言類問題。同理,測試、資料、法務(wù)背景的同事亦是如此,不同專長的人加入,更有利于充分地發(fā)現(xiàn)各種類型的問題。這點類似敏捷開發(fā)的全功能團隊。參與角色更全面,發(fā)現(xiàn)問題更充分。英雄不問出處,只要敢于挑戰(zhàn),均可參與戰(zhàn)碼先鋒,為開源項目添磚加瓦。
本文是基于一名技術(shù)筆譯的視角,從開發(fā)者體驗的角度和大家一起探討代碼文件中的常見資料類問題,并在此基礎(chǔ)上分享一些個人的建議。文章主要分為三個部分:資料內(nèi)容對于開發(fā)者生態(tài)的意義;影響資料體驗的典型問題;提升資料體驗的一些倡議。
首先,需要簡單了解一下資料內(nèi)容對于開發(fā)者生態(tài)的意義。
根據(jù)近幾年的開發(fā)者生態(tài)現(xiàn)狀和開源生態(tài)報告,完善、準確的內(nèi)容,是開發(fā)者選擇一個生態(tài)的重要因素之一。根據(jù)Accenture的調(diào)查報告顯示,開發(fā)者認為技術(shù)準確及最新的內(nèi)容(technically accurate and up-to-date content)是開發(fā)者生態(tài)中最為重要的兩個要素。
來源:ENGAGING THE DEVELOPER COMMUNITY - What Developer Ecosystems Need to Know,Accenture
OSCHINA和Gitee聯(lián)合發(fā)布的2021中國開源開發(fā)者報告,進一步佐證了這一點。從報告可以看出,相關(guān)文檔/資料是否豐富的重要性僅次于源碼質(zhì)量。
--摘自《2021中國開源開發(fā)者報告》
好的資料勝過千軍萬馬,資料的重要性不言而喻。好馬配好鞍,好的代碼要有好的資料配套,才能產(chǎn)生1+1大于2的效果,才能幫助開發(fā)者更好地上手,產(chǎn)生良好的開發(fā)者體驗,吸引更多的開發(fā)者參與。一個復(fù)雜的技術(shù)產(chǎn)品,如果沒有說明書,用戶就沒法高效、正確地使用該產(chǎn)品。代碼就好比復(fù)雜的產(chǎn)品,沒有完備的資料,開發(fā)者將無法理解源碼的作用和實現(xiàn)機制,在極大程度上影響其體驗。
對于OpenHarmony開源項目,文本內(nèi)容主要包含兩個部分:一是Docs倉中發(fā)布的文檔,包括但不限于開發(fā)指南、API參考等。二是代碼倉中包含的各種描述性信息,如readme、代碼注釋、log日志、API說明等。
那么,影響開發(fā)者體驗資料內(nèi)容質(zhì)量要素有哪些呢?
根據(jù)開發(fā)者生態(tài)相關(guān)報告,這些要素包括但不限于:accuracy(準確性)、completeness(完整性)、currency(時近性)、findability(檢索性)及readability(易讀性)。需要注意的是,此前的報告大多以主流開源項目作為基礎(chǔ)研究對象。這些項目主要由歐美Top玩家主導(dǎo),在語言文化方面有著天然優(yōu)勢,具備良好的國際化和本地化成熟度。因此,國際化、本地化、基礎(chǔ)語言質(zhì)量等方面同樣需要OpenHarmony開源項目重點關(guān)注。
接下來,我們將針對英文文本內(nèi)容,在戰(zhàn)碼先鋒活動中可關(guān)注哪些方面的典型問題?本次主要以非Docs倉的文本問題作為示例。
特別聲明:以下示例僅作為技術(shù)交流的示意用途,不構(gòu)成任何明示或暗示的聲明、陳述。同時,由于相關(guān)倉內(nèi)容在持續(xù)的變化更新,如有出入,請以實際為準。
一、準確清晰
示例1:辭不達意。這里API是DelUser,其功能為刪除用戶,因此描述應(yīng)該是Delete a user而非user authentication。
示例2:意思錯誤。PIN_MIXED是Mixed PIN鑒權(quán),F(xiàn)ACE_2D才是2D人臉識別鑒權(quán)。
示例3:含義相反。這里是inactive狀態(tài)的回調(diào),疊加語法錯誤,增加理解難度。實際含義應(yīng)為:Callback invoked in the main thread when an ability becomes inactive.
二、內(nèi)容完整
根據(jù)開源要求,開源代碼倉中注釋內(nèi)容均需英文化。受限于英文表達能力或內(nèi)部合規(guī)方面的考量,開發(fā)人員可能會傾向于刪除或者放棄提供一些需要英文化的必要內(nèi)容,如文件的簡述、實現(xiàn)機制或者注意等,如下例所示:左側(cè)enum缺少必要的注釋,開發(fā)者無法理解short period、normal period和long period的差異。
三、組織合理
信息的組織應(yīng)符合用戶的邏輯認知順序,例如,API介紹應(yīng)遵循“API功能說明+權(quán)限+參數(shù)說明+返回說明”的信息組織結(jié)構(gòu)。下面例子中,API名稱被直接替代為API功能說明,而實際的API功能說明則出現(xiàn)在permission之后。
參考修改如下:
四、一致性
一致性主要體現(xiàn)在風(fēng)格的一致性和內(nèi)容的一致性兩方面。
示例1:表達風(fēng)格不一致。如下日志描述中,上下兩行的大小寫風(fēng)格不一致:
示例2:內(nèi)容和實際不符。如下Readme中,目錄結(jié)構(gòu)中代碼倉名稱和實際代碼倉名稱不符:
五、基礎(chǔ)語言問題
示例1:拼寫錯誤出現(xiàn)在注釋語句或API名稱、參數(shù)等,如下例所示:faild拼寫錯誤,正確應(yīng)該為failed。
再看一個特例,這里pin雖然并非拼寫錯誤,但是實際上它是personal identification number的縮寫PIN,如寫成pin,表達的意思就完全不一樣了。
示例2:語法錯誤、表達不規(guī)范等問題在代碼文件中普遍存在,如下例所示:上下兩個句子風(fēng)格不一致。start device find for restart沒有使用sentence caps,第一個單詞首字母大寫。兩個句子均存在語法錯誤,而且因為用詞不當問題,兩個句子之間的內(nèi)在邏輯關(guān)聯(lián)沒有體現(xiàn),前面表示動作:Start discovery of devices for restart.后面則表示動作結(jié)果:Failed to start device discovery.
再來看一個示例,此處Active和Deactive為形容詞,不能代替動詞使用,對應(yīng)動詞應(yīng)該是Activate和Deactivate。
六、版式問題
單行內(nèi)容超寬,或者斷行不當?shù)葐栴}會造成版式不美觀。如下例所示,該句子被不當斷行,下面一行內(nèi)容可移到上面一行:
修改如下:
七、包容性
包容性語言是當今的一個重要趨勢,使用無偏見、包容性的措辭是品牌溫度在文化遵從和人文關(guān)懷方面的重要體現(xiàn)。一些原被接受認可的術(shù)語被逐步取代,如chairman、aldermen暗示男性的統(tǒng)治力,尤其是在對女性致辭/講話時。如下示例表達違反了包容性語言中角色和標簽的要求,應(yīng)該使用parent替代father:
還有一些值得我們關(guān)注的方面,如慎用定義階層、種族的術(shù)語。例如,當前行業(yè)和友商的做法是盡量用primary及secondary分別替換master和slave,用trustlist和blocklist分別替換blacklist及whitelist等。
以上是一些影響語言文化體驗的問題示例,我們在戰(zhàn)碼活動中可對此種類型的問題多加關(guān)注。
提升資料體驗的一些倡議
一個成功的生態(tài)離不開極致的開發(fā)者體驗。錯誤無論大小,都會給開發(fā)者體驗帶來不同程度的負面影響。借此機會,呼吁大家:
? 轉(zhuǎn)變觀念:開發(fā)者資料是開發(fā)者旅程(developer journey)中的關(guān)鍵一環(huán),對開發(fā)者體驗起著不可忽視的重要作用。對于開源項目,高質(zhì)量的資料更是開發(fā)者參與貢獻的基礎(chǔ)。產(chǎn)品功能和資料如天平的兩端,應(yīng)被賦予同樣的重視。
? 用戶視角:開發(fā)者是資料的第一讀者和用戶。在戰(zhàn)碼活動中,我們可基于開發(fā)者的視角去發(fā)現(xiàn)影響開發(fā)者完成任務(wù)的準確性、完整性、清晰性等各方面問題,積極去提Issue、PR,共同提升資料質(zhì)量。
? 低錯清零:一些低級錯誤不一定會阻礙用戶理解并完成任務(wù),但可以確定的是會對品牌的聲譽帶來負面影響。我們應(yīng)盡量去發(fā)現(xiàn)并修改此類問題,共同捍衛(wèi)OpenHarmony的質(zhì)量口碑。
歡迎感興趣的開發(fā)者朋友們一起參與戰(zhàn)碼先鋒,PR征集令!在Gitee的OpenHarmony代碼倉提交PR參與活動,和全球的開發(fā)者一起共建OpenHarmony的繁榮生態(tài)!現(xiàn)在就打開Gitee,為OpenHarmony提PR,你的一小步,就是OpenHarmony開源的一大步。
我們一群人在一起做一件偉大的事情,唯有共同攜手,在各自專長的領(lǐng)域去構(gòu)筑極致的開發(fā)者體驗,方能助力OpenHarmony生態(tài)行穩(wěn)致遠,也必將共同見證OpenHarmony成為萬物互聯(lián)時代的明珠。
若干年后,當我們回顧起這段歷史,我們可以對著開源貢獻者證書,自豪地對著我們的孩子說,這偉大的生態(tài)背后有著我們的一份努力和付出,這多么的讓人引以為傲。
-
文件
+關(guān)注
關(guān)注
1文章
555瀏覽量
24633 -
代碼
+關(guān)注
關(guān)注
30文章
4694瀏覽量
68075 -
開發(fā)者
+關(guān)注
關(guān)注
1文章
541瀏覽量
16956
原文標題:資深技術(shù)筆譯總結(jié)的這7條建議,看完提PR效率倍增
文章出處:【微信號:gh_e4f28cfa3159,微信公眾號:OpenAtom OpenHarmony】歡迎添加關(guān)注!文章轉(zhuǎn)載請注明出處。
發(fā)布評論請先 登錄
相關(guān)推薦
評論