戰(zhàn)碼先鋒，PR征集令（以下簡(jiǎn)稱“戰(zhàn)碼先鋒”）第二期正如火如荼地進(jìn)行中，涉及OpenAtom OpenHarmony（以下簡(jiǎn)稱“OpenHarmony”）主干倉(cāng)、SIG倉(cāng)、三方庫(kù)，共計(jì)1000+代碼倉(cāng)任君挑戰(zhàn)。

剛看到活動(dòng)的朋友們肯定有個(gè)疑問(wèn)：什么樣業(yè)務(wù)背景的人能參與戰(zhàn)碼先鋒活動(dòng)？是否可以找到提PR的一些基本方法？為此，我們邀請(qǐng)了戰(zhàn)碼先鋒第一期的貢獻(xiàn)者，也是第二期隊(duì)長(zhǎng)之一的King He為我們帶來(lái)了他的一些有效經(jīng)驗(yàn)。以下是他的分享。

實(shí)踐證明，來(lái)自不同背景的人，有助于充分發(fā)現(xiàn)問(wèn)題。如果你是一名翻譯，雖然不一定有深厚的技術(shù)功底，但你可以發(fā)揮專業(yè)能力，幫助大家發(fā)現(xiàn)項(xiàng)目中語(yǔ)言類問(wèn)題。同理，測(cè)試、資料、法務(wù)背景的同事亦是如此，不同專長(zhǎng)的人加入，更有利于充分地發(fā)現(xiàn)各種類型的問(wèn)題。這點(diǎn)類似敏捷開(kāi)發(fā)的全功能團(tuán)隊(duì)。參與角色更全面，發(fā)現(xiàn)問(wèn)題更充分。英雄不問(wèn)出處，只要敢于挑戰(zhàn)，均可參與戰(zhàn)碼先鋒，為開(kāi)源項(xiàng)目添磚加瓦。

本文是基于一名技術(shù)筆譯的視角，從開(kāi)發(fā)者體驗(yàn)的角度和大家一起探討代碼文件中的常見(jiàn)資料類問(wèn)題，并在此基礎(chǔ)上分享一些個(gè)人的建議。文章主要分為三個(gè)部分：資料內(nèi)容對(duì)于開(kāi)發(fā)者生態(tài)的意義；影響資料體驗(yàn)的典型問(wèn)題；提升資料體驗(yàn)的一些倡議。

首先，需要簡(jiǎn)單了解一下資料內(nèi)容對(duì)于開(kāi)發(fā)者生態(tài)的意義。

根據(jù)近幾年的開(kāi)發(fā)者生態(tài)現(xiàn)狀和開(kāi)源生態(tài)報(bào)告，完善、準(zhǔn)確的內(nèi)容，是開(kāi)發(fā)者選擇一個(gè)生態(tài)的重要因素之一。根據(jù)Accenture的調(diào)查報(bào)告顯示，開(kāi)發(fā)者認(rèn)為技術(shù)準(zhǔn)確及最新的內(nèi)容（technically accurate and up-to-date content）是開(kāi)發(fā)者生態(tài)中最為重要的兩個(gè)要素。

來(lái)源：ENGAGING THE DEVELOPER COMMUNITY - What Developer Ecosystems Need to Know，Accenture

OSCHINA和Gitee聯(lián)合發(fā)布的2021中國(guó)開(kāi)源開(kāi)發(fā)者報(bào)告，進(jìn)一步佐證了這一點(diǎn)。從報(bào)告可以看出，相關(guān)文檔/資料是否豐富的重要性僅次于源碼質(zhì)量。

-－摘自《2021中國(guó)開(kāi)源開(kāi)發(fā)者報(bào)告》

好的資料勝過(guò)千軍萬(wàn)馬，資料的重要性不言而喻。好馬配好鞍，好的代碼要有好的資料配套，才能產(chǎn)生1+1大于2的效果，才能幫助開(kāi)發(fā)者更好地上手，產(chǎn)生良好的開(kāi)發(fā)者體驗(yàn)，吸引更多的開(kāi)發(fā)者參與。一個(gè)復(fù)雜的技術(shù)產(chǎn)品，如果沒(méi)有說(shuō)明書，用戶就沒(méi)法高效、正確地使用該產(chǎn)品。代碼就好比復(fù)雜的產(chǎn)品，沒(méi)有完備的資料，開(kāi)發(fā)者將無(wú)法理解源碼的作用和實(shí)現(xiàn)機(jī)制，在極大程度上影響其體驗(yàn)。

對(duì)于OpenHarmony開(kāi)源項(xiàng)目，文本內(nèi)容主要包含兩個(gè)部分：一是Docs倉(cāng)中發(fā)布的文檔，包括但不限于開(kāi)發(fā)指南、API參考等。二是代碼倉(cāng)中包含的各種描述性信息，如readme、代碼注釋、log日志、API說(shuō)明等。

那么，影響開(kāi)發(fā)者體驗(yàn)資料內(nèi)容質(zhì)量要素有哪些呢？

根據(jù)開(kāi)發(fā)者生態(tài)相關(guān)報(bào)告，這些要素包括但不限于：accuracy（準(zhǔn)確性）、completeness（完整性）、currency（時(shí)近性）、findability（檢索性）及readability（易讀性）。需要注意的是，此前的報(bào)告大多以主流開(kāi)源項(xiàng)目作為基礎(chǔ)研究對(duì)象。這些項(xiàng)目主要由歐美Top玩家主導(dǎo)，在語(yǔ)言文化方面有著天然優(yōu)勢(shì)，具備良好的國(guó)際化和本地化成熟度。因此，國(guó)際化、本地化、基礎(chǔ)語(yǔ)言質(zhì)量等方面同樣需要OpenHarmony開(kāi)源項(xiàng)目重點(diǎn)關(guān)注。

接下來(lái)，我們將針對(duì)英文文本內(nèi)容，在戰(zhàn)碼先鋒活動(dòng)中可關(guān)注哪些方面的典型問(wèn)題？本次主要以非Docs倉(cāng)的文本問(wèn)題作為示例。

特別聲明：以下示例僅作為技術(shù)交流的示意用途，不構(gòu)成任何明示或暗示的聲明、陳述。同時(shí)，由于相關(guān)倉(cāng)內(nèi)容在持續(xù)的變化更新，如有出入，請(qǐng)以實(shí)際為準(zhǔn)。

一、準(zhǔn)確清晰

示例1：辭不達(dá)意。這里API是DelUser，其功能為刪除用戶，因此描述應(yīng)該是Delete a user而非user authentication。

示例2：意思錯(cuò)誤。PIN_MIXED是Mixed PIN鑒權(quán)，F(xiàn)ACE_2D才是2D人臉識(shí)別鑒權(quán)。

示例3：含義相反。這里是inactive狀態(tài)的回調(diào)，疊加語(yǔ)法錯(cuò)誤，增加理解難度。實(shí)際含義應(yīng)為：Callback invoked in the main thread when an ability becomes inactive.

二、內(nèi)容完整

根據(jù)開(kāi)源要求，開(kāi)源代碼倉(cāng)中注釋內(nèi)容均需英文化。受限于英文表達(dá)能力或內(nèi)部合規(guī)方面的考量，開(kāi)發(fā)人員可能會(huì)傾向于刪除或者放棄提供一些需要英文化的必要內(nèi)容，如文件的簡(jiǎn)述、實(shí)現(xiàn)機(jī)制或者注意等，如下例所示：左側(cè)enum缺少必要的注釋，開(kāi)發(fā)者無(wú)法理解short period、normal period和long period的差異。

三、組織合理

信息的組織應(yīng)符合用戶的邏輯認(rèn)知順序，例如，API介紹應(yīng)遵循“API功能說(shuō)明+權(quán)限+參數(shù)說(shuō)明+返回說(shuō)明”的信息組織結(jié)構(gòu)。下面例子中，API名稱被直接替代為API功能說(shuō)明，而實(shí)際的API功能說(shuō)明則出現(xiàn)在permission之后。

參考修改如下：

四、一致性

一致性主要體現(xiàn)在風(fēng)格的一致性和內(nèi)容的一致性兩方面。

示例1：表達(dá)風(fēng)格不一致。如下日志描述中，上下兩行的大小寫風(fēng)格不一致：

示例2：內(nèi)容和實(shí)際不符。如下Readme中，目錄結(jié)構(gòu)中代碼倉(cāng)名稱和實(shí)際代碼倉(cāng)名稱不符：

五、基礎(chǔ)語(yǔ)言問(wèn)題

示例1：拼寫錯(cuò)誤出現(xiàn)在注釋語(yǔ)句或API名稱、參數(shù)等，如下例所示：faild拼寫錯(cuò)誤，正確應(yīng)該為failed。

再看一個(gè)特例，這里pin雖然并非拼寫錯(cuò)誤，但是實(shí)際上它是personal identification number的縮寫PIN，如寫成pin，表達(dá)的意思就完全不一樣了。

示例2：語(yǔ)法錯(cuò)誤、表達(dá)不規(guī)范等問(wèn)題在代碼文件中普遍存在，如下例所示：上下兩個(gè)句子風(fēng)格不一致。start device find for restart沒(méi)有使用sentence caps，第一個(gè)單詞首字母大寫。兩個(gè)句子均存在語(yǔ)法錯(cuò)誤，而且因?yàn)橛迷~不當(dāng)問(wèn)題，兩個(gè)句子之間的內(nèi)在邏輯關(guān)聯(lián)沒(méi)有體現(xiàn)，前面表示動(dòng)作：Start discovery of devices for restart.后面則表示動(dòng)作結(jié)果：Failed to start device discovery.

再來(lái)看一個(gè)示例，此處Active和Deactive為形容詞，不能代替動(dòng)詞使用，對(duì)應(yīng)動(dòng)詞應(yīng)該是Activate和Deactivate。

六、版式問(wèn)題

單行內(nèi)容超寬，或者斷行不當(dāng)?shù)葐?wèn)題會(huì)造成版式不美觀。如下例所示，該句子被不當(dāng)斷行，下面一行內(nèi)容可移到上面一行：

修改如下：

七、包容性

包容性語(yǔ)言是當(dāng)今的一個(gè)重要趨勢(shì)，使用無(wú)偏見(jiàn)、包容性的措辭是品牌溫度在文化遵從和人文關(guān)懷方面的重要體現(xiàn)。一些原被接受認(rèn)可的術(shù)語(yǔ)被逐步取代，如chairman、aldermen暗示男性的統(tǒng)治力，尤其是在對(duì)女性致辭/講話時(shí)。如下示例表達(dá)違反了包容性語(yǔ)言中角色和標(biāo)簽的要求，應(yīng)該使用parent替代father：

還有一些值得我們關(guān)注的方面，如慎用定義階層、種族的術(shù)語(yǔ)。例如，當(dāng)前行業(yè)和友商的做法是盡量用primary及secondary分別替換master和slave，用trustlist和blocklist分別替換blacklist及whitelist等。

以上是一些影響語(yǔ)言文化體驗(yàn)的問(wèn)題示例，我們?cè)趹?zhàn)碼活動(dòng)中可對(duì)此種類型的問(wèn)題多加關(guān)注。

提升資料體驗(yàn)的一些倡議

一個(gè)成功的生態(tài)離不開(kāi)極致的開(kāi)發(fā)者體驗(yàn)。錯(cuò)誤無(wú)論大小，都會(huì)給開(kāi)發(fā)者體驗(yàn)帶來(lái)不同程度的負(fù)面影響。借此機(jī)會(huì)，呼吁大家：

? 轉(zhuǎn)變觀念：開(kāi)發(fā)者資料是開(kāi)發(fā)者旅程（developer journey）中的關(guān)鍵一環(huán)，對(duì)開(kāi)發(fā)者體驗(yàn)起著不可忽視的重要作用。對(duì)于開(kāi)源項(xiàng)目，高質(zhì)量的資料更是開(kāi)發(fā)者參與貢獻(xiàn)的基礎(chǔ)。產(chǎn)品功能和資料如天平的兩端，應(yīng)被賦予同樣的重視。

? 用戶視角：開(kāi)發(fā)者是資料的第一讀者和用戶。在戰(zhàn)碼活動(dòng)中，我們可基于開(kāi)發(fā)者的視角去發(fā)現(xiàn)影響開(kāi)發(fā)者完成任務(wù)的準(zhǔn)確性、完整性、清晰性等各方面問(wèn)題，積極去提Issue、PR，共同提升資料質(zhì)量。

? 低錯(cuò)清零：一些低級(jí)錯(cuò)誤不一定會(huì)阻礙用戶理解并完成任務(wù)，但可以確定的是會(huì)對(duì)品牌的聲譽(yù)帶來(lái)負(fù)面影響。我們應(yīng)盡量去發(fā)現(xiàn)并修改此類問(wèn)題，共同捍衛(wèi)OpenHarmony的質(zhì)量口碑。

歡迎感興趣的開(kāi)發(fā)者朋友們一起參與戰(zhàn)碼先鋒，PR征集令！在Gitee的OpenHarmony代碼倉(cāng)提交PR參與活動(dòng)，和全球的開(kāi)發(fā)者一起共建OpenHarmony的繁榮生態(tài)！現(xiàn)在就打開(kāi)Gitee，為OpenHarmony提PR，你的一小步，就是OpenHarmony開(kāi)源的一大步。

我們一群人在一起做一件偉大的事情，唯有共同攜手，在各自專長(zhǎng)的領(lǐng)域去構(gòu)筑極致的開(kāi)發(fā)者體驗(yàn)，方能助力OpenHarmony生態(tài)行穩(wěn)致遠(yuǎn)，也必將共同見(jiàn)證OpenHarmony成為萬(wàn)物互聯(lián)時(shí)代的明珠。

若干年后，當(dāng)我們回顧起這段歷史，我們可以對(duì)著開(kāi)源貢獻(xiàn)者證書，自豪地對(duì)著我們的孩子說(shuō)，這偉大的生態(tài)背后有著我們的一份努力和付出，這多么的讓人引以為傲。