代碼文件中的常見資料類問題

戰(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)背后有著我們的一份努力和付出，這多么的讓人引以為傲。