从Docs仓 开启OpenHarmony社区达人进阶之旅

战“码”先锋，PR 征集令活动正如火如荼地进行中，截至 6 月 6 日，提交 PR 总数 678个，合入 PR 数 363 个。为了更好地赋能开发者，帮助大家更加便利地参与社区活动，成为社区达人。

我们邀请 OpenAtom OpenHarmony（以下简称“OpenHarmony”） SIG Docs 的 Committer – NEEN YANG，为大家分享《参与文档贡献，开启 OpenHarmony 社区贡献进阶之旅》。她从：文档的作用、好文档的三个特性、文档贡献的形式、文档 PR 的类别、OpenHarmony社区文档类型等 6 个方面为大家详细介绍了如何为 OpenHarmony 社区贡献文档 PR。

参与战“码”先锋，PR 征集令！你可以在 Gitee 的 OpenHarmony 代码仓提交 PR 参与活动，和全球开发者同台竞技，比拼技艺，为 OpenHarmony 贡献力量。

 

文档的重要性

文档对开源项目有着非常重要的意义，是开发者熟悉项目的第一步，也是开发者考虑是否参与项目的重要因素。在开源中国联合 Gitee发布的《2021 中国开源开发者报告》中指出：60% 的开发者将相关文档/资料是否丰富作为使用开源软件场景的重要条件。除此之外，在 GitHub 于 2021 年发布的报告中也明确提出，开源项目中更新及时、资源丰富的文档，能够帮助开发人员平均产出提升 50%。  

好文档的特性

好的文档是一个好的开始。如何写出好的文档，一本面向技术写作者的参考书籍：Developing Quality Technical Information: A Handbook for Writers and Editors 给出了解释。它将文档质量按照用户视角分为三个方面：易使用、易理解、易查找。 其中易使用指的是文档符合用户场景帮助用户高效完成任务，具体从用户任务视角、内容正确、内容完整三个维度进行定义。易理解即：内容清晰、描述具体、风格一致，这样能够帮助开发者快速理解文档意义和方便后续对项目的学习。易查找是指内容获取是否高效便捷，从信息架构、可检索、视觉效果三个维度进行定义。  

有了好文档的定义，要写出这样一份具备三易特征的好文档，技术写作者需要具备哪些能力？NEEN YANG 在分享中给出的解释是，首先要具备好的技术理解力，要站在用户的视角，写出面向用户的任务式的文档。同时要确保内容的结构设计合理、逻辑清晰。还要具备开发者的同理心，例如内容的难易程度，相关知识的颗粒度，需要考虑对不同类型的开发者有不同的写作风格。最后是语言的表达需要行文流畅，通俗易懂。  

文档贡献的三种形式

首先大家在使用 OpenHarmony 的代码时，遇到任何问题，提出问题就是一种贡献。例如在运行某一段示例代码，发现示例代码运行时报错，或发现文档中操作步骤有误，亦或是发现内容不完整等，提出问题就能够帮助项目改善优化。在其他开发者遇到类似问题时，问题的修复也避免了大家重复试错。当大家对 OpenHarmony 的产品能力已经有了一定的认知，便可以参与具体的子系统、技术领域学习与贡献。随着技能成长，也会涌现出一些专家，这样就能够参与文档的评审。 在参与文档评审前，建议大家先要了解文档的贡献指南，了解如何参与贡献。接着了解风格指南，该指南针对 OpenHarmony 文档的语言风格、文档结构、内容元素等提供规范要求或参考建议，确保 OpenHarmony 文档具备一致的风格，同时帮助开发者高效参与文档贡献。同时需要注意的是写作模板，了解不同类别文档内容的模板定义要求，信息要素。最后学习编程规范，了解不同编码语言规范要求，确保能够写出符合规范要求的代码、示例。

掌握了基础知识，大家就可以提交 Pull Request 参与内容贡献。在此之前，也建议大家先熟悉 Markdown 编写语法技巧、熟悉 Git/Gitee 平台使用方法。查阅并借鉴其他贡献者发起的 Issue 或 PR，贡献此类内容。

贡献文档PR的类型

对于新手开发者来说，规范性的内容修复是一个好的开始。社区提供了 OpenHarmony 风格指导和模板要求，大家可以根据相关规范要求，在学习和使用文档过程中，发现文档中不符合风格要求或模板要求的问题。如缺少信息元素、描述风格问题，资料规范问题、代码规范问题，Markdown 规范、术语一致性、逻辑表达不清晰、标点符合或链接缺失等基础问题，通过提交 Pull Request 进行修复。 有一定经验的开发者可能会参与小功能开发、测试、体验，也可能研究源码。在这些活动过程中，可能会发现文档内容的准确性和可用性方面的问题。 随着参与贡献，技能得到不断提升，可能你已经进阶为一位资深的开发者。具备独立贡献新内容的能力，例如在处理某一个大家经常遇到的问题后，形成了一些经验，可以贡献一篇 FAQ，分享问题处理经验指导。或者在使用社区里其他第三方贡献的工具、测试能力时，可以为这些工具撰写使用指导，帮助更多开发者快速上手。社区第三方的芯片厂家、开发板厂商参与芯片移植过程，贡献了多篇芯片移植案例；技术翻译专业的同学们，也可以参与本地化翻译贡献内容。

贡献的内容可以多样，但需要各位开发者谨记尊重原创，一切为了开发者的原则。能够提升开发者体验，帮助开发者更加高效地学习、开发、调测、问题处理，这些内容贡献都是我们倡导的。

提交文档PR示例

方法和经验都有了，我们来看几个样例。瞄准文档基础规范类型发现问题并修复，社区小白也能得心应手提 PR。比如以下的几个 PR，分别从修复拼写错误、优化文档描述、修复链接等几个方面展示了几个基础规范类文档 PR。  

对于有经验的开发者，可以发现内容的准确性和可用性的问题，并做相应的修复。此处以社区开发者九弓子的问题反馈举例，在 RK3568 开发板烧录时，工具提示了烧录异常处理指导，文档中未明确提醒，开发者容易忽略“烧录异常”的相关提示。通过在文档中提 PR，增加相关提示，提醒其他开发者规避此类问题，帮助他们更高效地完成开发板烧录。

还有一个非常重要的贡献方式：贡献新内容。示例是 OpenHarmony 社区共建伙伴拓维信息贡献的芯片移植案例，将芯片移植的过程、经验、问题处理等总结成为移植案例，帮助社区更多芯片厂商等参考借鉴，为社区生态繁荣做出了贡献。

OpenHarmony社区文档展示

从开发者官网进入后，选择支持-文档页，即可一站式便捷获取所有 OpenHarmony 核心功能配套的入门基础知识、应用开发、开发板开发快速上手；便于学习上手的代码示例、Codelabs 教程；各子系统/特性开发指南、工具使用指南、API 参考等。同时，可以获取开发者关注的版本更新说明、API接口变更、常见问题、贡献指导等专题。

我们欣喜地发现，有 400+ 位社区开发者参与了 OpenHarmony Docs 仓贡献，感谢大家的持续关注和反馈。欢迎更多的开发者在参与 OpenHarmony 开源项目中，持续关注 SIG Docs，反馈文档建议和需求，与我们一同持续提升文档体验。

我们坚信社区开发者的共建力量，携手同行、并肩协作，打造健康、蓬勃发展的 OpenHarmony 社区。也期待更多的文档贡献者、最佳贡献者产生。

 

相关资源汇总

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编程规范

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

OpenHarmony社区文档生产流程

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