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

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

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

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

文檔的重要性

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

好文檔的特性

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

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

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

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

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

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

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

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

提交文檔PR示例

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

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

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

OpenHarmony社區(qū)文檔展示

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

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

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

相關(guān)資源匯總

OpenHarmony Docs倉(cāng)

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