從Docs倉 開啟OpenHarmony社區(qū)達人進階之旅

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

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

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

文檔的重要性

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

好文檔的特性

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

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

文檔貢獻的三種形式

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

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

貢獻文檔PR的類型

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

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

提交文檔PR示例

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

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

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

OpenHarmony社區(qū)文檔展示

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

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

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

相關資源匯總

OpenHarmony Docs倉

https://gitee.com/openharmony/docs

OpenHarmony官網

https://docs.openharmony.cn/

OpenHarmony貢獻指南

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

OpenHarmony風格指導

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ū)文檔生產流程

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