戰碼先鋒，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成為萬物互聯時代的明珠。

若干年后，當我們回顧起這段歷史，我們可以對著開源貢獻者證書，自豪地對著我們的孩子說，這偉大的生態背后有著我們的一份努力和付出，這多么的讓人引以為傲。