從Docs倉 開啟OpenHarmony社區(qū)達(dá)人進(jìn)階之旅

戰(zhàn)“碼”先鋒，PR 征集令活動正如火如荼地進(jìn)行中，截至 6 月 6 日，提交 PR 總數(shù) 678個，合入 PR 數(shù) 363 個。為了更好地賦能開發(fā)者，幫助大家更加便利地參與社區(qū)活動，成為社區(qū)達(dá)人。

我們邀請 OpenAtom OpenHarmony（以下簡稱“OpenHarmony”） SIG Docs 的 Committer – NEEN YANG，為大家分享《參與文檔貢獻(xiàn)，開啟 OpenHarmony 社區(qū)貢獻(xiàn)進(jìn)階之旅》。她從：文檔的作用、好文檔的三個特性、文檔貢獻(xiàn)的形式、文檔 PR 的類別、OpenHarmony社區(qū)文檔類型等 6 個方面為大家詳細(xì)介紹了如何為 OpenHarmony 社區(qū)貢獻(xiàn)文檔 PR。

參與戰(zhàn)“碼”先鋒，PR 征集令！你可以在 Gitee 的 OpenHarmony 代碼倉提交 PR 參與活動，和全球開發(fā)者同臺競技，比拼技藝，為 OpenHarmony 貢獻(xiàn)力量。

文檔的重要性

文檔對開源項(xiàng)目有著非常重要的意義，是開發(fā)者熟悉項(xiàng)目的第一步，也是開發(fā)者考慮是否參與項(xiàng)目的重要因素。在開源中國聯(lián)合 Gitee發(fā)布的《2021 中國開源開發(fā)者報(bào)告》中指出：60% 的開發(fā)者將相關(guān)文檔/資料是否豐富作為使用開源軟件場景的重要條件。除此之外，在 GitHub 于 2021 年發(fā)布的報(bào)告中也明確提出，開源項(xiàng)目中更新及時(shí)、資源豐富的文檔，能夠幫助開發(fā)人員平均產(chǎn)出提升 50%。

好文檔的特性

好的文檔是一個好的開始。如何寫出好的文檔，一本面向技術(shù)寫作者的參考書籍：Developing Quality Technical Information: A Handbook for Writers and Editors 給出了解釋。它將文檔質(zhì)量按照用戶視角分為三個方面：易使用、易理解、易查找。 其中易使用指的是文檔符合用戶場景幫助用戶高效完成任務(wù)，具體從用戶任務(wù)視角、內(nèi)容正確、內(nèi)容完整三個維度進(jìn)行定義。易理解即：內(nèi)容清晰、描述具體、風(fēng)格一致，這樣能夠幫助開發(fā)者快速理解文檔意義和方便后續(xù)對項(xiàng)目的學(xué)習(xí)。易查找是指內(nèi)容獲取是否高效便捷，從信息架構(gòu)、可檢索、視覺效果三個維度進(jìn)行定義。

有了好文檔的定義，要寫出這樣一份具備三易特征的好文檔，技術(shù)寫作者需要具備哪些能力？NEEN YANG 在分享中給出的解釋是，首先要具備好的技術(shù)理解力，要站在用戶的視角，寫出面向用戶的任務(wù)式的文檔。同時(shí)要確保內(nèi)容的結(jié)構(gòu)設(shè)計(jì)合理、邏輯清晰。還要具備開發(fā)者的同理心，例如內(nèi)容的難易程度，相關(guān)知識的顆粒度，需要考慮對不同類型的開發(fā)者有不同的寫作風(fēng)格。最后是語言的表達(dá)需要行文流暢，通俗易懂。

文檔貢獻(xiàn)的三種形式

首先大家在使用 OpenHarmony 的代碼時(shí)，遇到任何問題，提出問題就是一種貢獻(xiàn)。例如在運(yùn)行某一段示例代碼，發(fā)現(xiàn)示例代碼運(yùn)行時(shí)報(bào)錯，或發(fā)現(xiàn)文檔中操作步驟有誤，亦或是發(fā)現(xiàn)內(nèi)容不完整等，提出問題就能夠幫助項(xiàng)目改善優(yōu)化。在其他開發(fā)者遇到類似問題時(shí)，問題的修復(fù)也避免了大家重復(fù)試錯。當(dāng)大家對 OpenHarmony 的產(chǎn)品能力已經(jīng)有了一定的認(rèn)知，便可以參與具體的子系統(tǒng)、技術(shù)領(lǐng)域?qū)W習(xí)與貢獻(xiàn)。隨著技能成長，也會涌現(xiàn)出一些專家，這樣就能夠參與文檔的評審。 在參與文檔評審前，建議大家先要了解文檔的貢獻(xiàn)指南，了解如何參與貢獻(xiàn)。接著了解風(fēng)格指南，該指南針對 OpenHarmony 文檔的語言風(fēng)格、文檔結(jié)構(gòu)、內(nèi)容元素等提供規(guī)范要求或參考建議，確保 OpenHarmony 文檔具備一致的風(fēng)格，同時(shí)幫助開發(fā)者高效參與文檔貢獻(xiàn)。同時(shí)需要注意的是寫作模板，了解不同類別文檔內(nèi)容的模板定義要求，信息要素。最后學(xué)習(xí)編程規(guī)范，了解不同編碼語言規(guī)范要求，確保能夠?qū)懗龇弦?guī)范要求的代碼、示例。

掌握了基礎(chǔ)知識，大家就可以提交 Pull Request 參與內(nèi)容貢獻(xiàn)。在此之前，也建議大家先熟悉 Markdown 編寫語法技巧、熟悉 Git/Gitee 平臺使用方法。查閱并借鑒其他貢獻(xiàn)者發(fā)起的 Issue 或 PR，貢獻(xiàn)此類內(nèi)容。

貢獻(xiàn)文檔PR的類型

對于新手開發(fā)者來說，規(guī)范性的內(nèi)容修復(fù)是一個好的開始。社區(qū)提供了 OpenHarmony 風(fēng)格指導(dǎo)和模板要求，大家可以根據(jù)相關(guān)規(guī)范要求，在學(xué)習(xí)和使用文檔過程中，發(fā)現(xiàn)文檔中不符合風(fēng)格要求或模板要求的問題。如缺少信息元素、描述風(fēng)格問題，資料規(guī)范問題、代碼規(guī)范問題，Markdown 規(guī)范、術(shù)語一致性、邏輯表達(dá)不清晰、標(biāo)點(diǎn)符合或鏈接缺失等基礎(chǔ)問題，通過提交 Pull Request 進(jìn)行修復(fù)。 有一定經(jīng)驗(yàn)的開發(fā)者可能會參與小功能開發(fā)、測試、體驗(yàn)，也可能研究源碼。在這些活動過程中，可能會發(fā)現(xiàn)文檔內(nèi)容的準(zhǔn)確性和可用性方面的問題。 隨著參與貢獻(xiàn)，技能得到不斷提升，可能你已經(jīng)進(jìn)階為一位資深的開發(fā)者。具備獨(dú)立貢獻(xiàn)新內(nèi)容的能力，例如在處理某一個大家經(jīng)常遇到的問題后，形成了一些經(jīng)驗(yàn)，可以貢獻(xiàn)一篇 FAQ，分享問題處理經(jīng)驗(yàn)指導(dǎo)?；蛘咴谑褂蒙鐓^(qū)里其他第三方貢獻(xiàn)的工具、測試能力時(shí)，可以為這些工具撰寫使用指導(dǎo)，幫助更多開發(fā)者快速上手。社區(qū)第三方的芯片廠家、開發(fā)板廠商參與芯片移植過程，貢獻(xiàn)了多篇芯片移植案例；技術(shù)翻譯專業(yè)的同學(xué)們，也可以參與本地化翻譯貢獻(xiàn)內(nèi)容。

貢獻(xiàn)的內(nèi)容可以多樣，但需要各位開發(fā)者謹(jǐn)記尊重原創(chuàng)，一切為了開發(fā)者的原則。能夠提升開發(fā)者體驗(yàn)，幫助開發(fā)者更加高效地學(xué)習(xí)、開發(fā)、調(diào)測、問題處理，這些內(nèi)容貢獻(xiàn)都是我們倡導(dǎo)的。

提交文檔PR示例

方法和經(jīng)驗(yàn)都有了，我們來看幾個樣例。瞄準(zhǔn)文檔基礎(chǔ)規(guī)范類型發(fā)現(xiàn)問題并修復(fù)，社區(qū)小白也能得心應(yīng)手提 PR。比如以下的幾個 PR，分別從修復(fù)拼寫錯誤、優(yōu)化文檔描述、修復(fù)鏈接等幾個方面展示了幾個基礎(chǔ)規(guī)范類文檔 PR。

對于有經(jīng)驗(yàn)的開發(fā)者，可以發(fā)現(xiàn)內(nèi)容的準(zhǔn)確性和可用性的問題，并做相應(yīng)的修復(fù)。此處以社區(qū)開發(fā)者九弓子的問題反饋舉例，在 RK3568 開發(fā)板燒錄時(shí)，工具提示了燒錄異常處理指導(dǎo)，文檔中未明確提醒，開發(fā)者容易忽略“燒錄異?！钡南嚓P(guān)提示。通過在文檔中提 PR，增加相關(guān)提示，提醒其他開發(fā)者規(guī)避此類問題，幫助他們更高效地完成開發(fā)板燒錄。

還有一個非常重要的貢獻(xiàn)方式：貢獻(xiàn)新內(nèi)容。示例是 OpenHarmony 社區(qū)共建伙伴拓維信息貢獻(xiàn)的芯片移植案例，將芯片移植的過程、經(jīng)驗(yàn)、問題處理等總結(jié)成為移植案例，幫助社區(qū)更多芯片廠商等參考借鑒，為社區(qū)生態(tài)繁榮做出了貢獻(xiàn)。

OpenHarmony社區(qū)文檔展示

從開發(fā)者官網(wǎng)進(jìn)入后，選擇支持-文檔頁，即可一站式便捷獲取所有 OpenHarmony 核心功能配套的入門基礎(chǔ)知識、應(yīng)用開發(fā)、開發(fā)板開發(fā)快速上手；便于學(xué)習(xí)上手的代碼示例、Codelabs 教程；各子系統(tǒng)/特性開發(fā)指南、工具使用指南、API 參考等。同時(shí)，可以獲取開發(fā)者關(guān)注的版本更新說明、API接口變更、常見問題、貢獻(xiàn)指導(dǎo)等專題。

我們欣喜地發(fā)現(xiàn)，有 400+ 位社區(qū)開發(fā)者參與了 OpenHarmony Docs 倉貢獻(xiàn)，感謝大家的持續(xù)關(guān)注和反饋。歡迎更多的開發(fā)者在參與 OpenHarmony 開源項(xiàng)目中，持續(xù)關(guān)注 SIG Docs，反饋文檔建議和需求，與我們一同持續(xù)提升文檔體驗(yàn)。

我們堅(jiān)信社區(qū)開發(fā)者的共建力量，攜手同行、并肩協(xié)作，打造健康、蓬勃發(fā)展的 OpenHarmony 社區(qū)。也期待更多的文檔貢獻(xiàn)者、最佳貢獻(xiàn)者產(chǎn)生。

相關(guān)資源匯總

OpenHarmony Docs倉

https://gitee.com/openharmony/docs

OpenHarmony官網(wǎng)

https://docs.openharmony.cn/

OpenHarmony貢獻(xiàn)指南

https://gitee.com/openharmony/docs/tree/master/zh-cn/contribute

OpenHarmony風(fēng)格指導(dǎo)

https://gitee.com/openharmony/docs/tree/master/zh-cn/contribute/style-guide

OpenHarmony文檔模板

https://gitee.com/openharmony/docs/tree/master/zh-cn/contribute/template

OpenHarmony編程規(guī)范

https://gitee.com/openharmony/community/blob/master/sig/sig-QA/%E7%BC%96%E8%AF%91%E8%A7%84%E8%8C%83.md

OpenHarmony社區(qū)文檔生產(chǎn)流程

https://gitee.com/openharmony/docs/blob/master/zh-cn/contribute/docs-release-process.md