RNOH 社区文档共建指南：ohos_react_native 开发者文档的写作、分类与提交规范

本文基于 docs/en/06-community/documentation-contribution-guide.md 及其中文版 docs/zh-cn/06-社区/开发者文档共建指南.md，结合 ohos_react_native（React Native for OpenHarmony，简称 RNOH）仓库中的文档目录结构、导航文件与配套 Skill 展开。读完本文，你将掌握：RNOH 文档按「开发者旅程」如何组织目录、文档编写与双语同步有哪些硬性规范、如何判定一篇新文档的归属目录与版本相关性、以及提交 PR 与通过审核的全套流程，从而能够以统一标准参与 RNOH 社区文档共建，保证文档质量一致、维护高效。

一、文档目录结构：按「开发者旅程」组织全生命周期

RNOH 文档不是按模块或团队划分，而是按**开发者旅程（Developer Journey）**组织，覆盖从设计到运维的全生命周期。每个阶段一个顶级目录，共六个阶段：

目录	旅程阶段	核心内容	版本相关
01-design	设计	接口规格、架构规划、通信机制	❌
02-development	开发	环境搭建、功能开发、组件定制	✅ 部分
03-debugging	调测	调试方法、问题定位、FAQ	❌
04-optimization	调优	性能优化、实践案例	❌
05-operations	运维	版本管理、稳定性管理、构建打包	✅
06-community	社区治理	社区规范、共建指南、路线图	❌

在仓库中，这套结构以中英双语双份存在：中文版位于 docs/zh-cn/，英文版位于 docs/en/。例如中文 02-开发 下细分为 01-环境与工具/、02-开发指南/、03-场景与实践/ 三个子目录（见 docs/zh-cn/02-开发/README.md），英文 02-development 下对应 01-environment-and-tools/、02-development-guide/、03-scenarios-and-practices/（见 docs/en/02-development/README.md）。顶层 docs/zh-cn/README.md 与 docs/en/README.md 的「开发者旅程导航」表格即是对这六个阶段的汇总入口。

版本相关文档标识

部分文档的内容与 React Native 具体版本强绑定，需要随每次版本发布同步更新。目前被标记为版本相关的文档集中在两个目录：

目录	版本相关文件
02-开发	环境搭建.md、SDK版本配置指导.md、Autolinking.md
05-运维	版本说明.md、版本升级指导.md、release-notes/、RN-JS打包.md、稳定性历史修复/

对照英文目录：02-development 下对应 environment-setup.md、SDK version configuration guide.md、autolinking.md；05-operations 下对应 release-notes-overview.md、version-upgrade-guide.md、release-notes/、rn-js-bundle.md。这些文件在 docs/zh-cn/05-运维/README.md 中被用 ⚡ 符号明确标注为「版本相关」，例如 稳定版本识别与安装.md、版本说明.md、版本升级指导.md、RN升级需要开发者适配整理.md、上游社区不兼容变更.md、RN-JS打包.md、hvigorfile配置.md、稳定性历史修复/ 均属于此列。

二、文档编写规范

文件命名规范

规范项	中文	英文
文件名	中文命名，无空格，使用连字符	小写英文，使用连字符
编码	UTF-8 无 BOM	UTF-8 无 BOM
格式	Markdown (.md)	Markdown (.md)

示例：

• 中文：版本升级指导.md、调试调测.md（对应仓库中的 docs/zh-cn/05-运维/版本升级指导.md、docs/zh-cn/03-调测/调试调测.md）
• 英文：version-upgrade-guide.md、debugging.md（对应 docs/en/05-operations/version-upgrade-guide.md、docs/en/03-debugging/debugging.md）

需要说明的是，中文文档名中「调试」与「调测」的用法在仓库内并不完全统一——03-调测 目录内的文件名为 调试调测.md，而 02-开发/03-场景与实践/ 下有 使用类FAQ.md，05-运维 下有 多屏适配指导.md。命名规范要求「中文命名、无空格」，新建文档时建议参考同目录已有文件的命名习惯，保持一致性。

文档头部模板

每个文档开头必须包含以下元信息（版本相关文档必须标注适用版本）：

# 文档标题

> 适用版本：v0.72 / v0.77 / v0.82 / v0.84 / v0.86（版本相关文档需标注）
> 开发者旅程：设计 / 开发 / 调测 / 调优 / 测试 / 运维
> 最后更新：YYYY-MM-DD
> 贡献者：@username

## 概述

简要说明文档目的与适用场景。

这一头部模板与仓库中的版本节奏一致——docs/zh-cn/06-社区/roadmap.md 显示，RNOH 社区版已交付/规划 0.72、0.77、0.82、0.84、0.86、0.88 等适配版本，因此「适用版本」一栏的候选值随版本演进会持续扩充。若某篇文档暂时无法标注英文，可在头部补充 > 英文版本待同步，欢迎社区贡献翻译。

内容编写要求

要求	说明
标题层级	最多 4 级（# → ## → ### → ####），禁止跳级
段落长度	每段不超过 5 行，便于阅读
代码示例	必须标注语言，提供完整可运行示例
图片规范	存放于 figures/ 目录，使用相对路径引用
链接规范	优先使用相对路径，外部链接需标注来源

仓库中已有大量符合此规范的文档可作范例，例如 docs/en/01-design/architecture.md（架构原理）、docs/en/02-development/02-development-guide/custom-components.md（组件定制）、docs/en/05-operations/rn-js-bundle.md（JS 打包）。各阶段目录下的 README.md 即用「导航表格 + 目录树」两种形式组织文档索引，同时也可作为「段落简洁、层级规范」的排版参照。

三、双语文档处理规范

双语文件对应规则

中英文文档按对应目录层级一致的原则一一对应：

中文文件	英文文件	位置关系
docs/zh-cn/01-设计/架构介绍.md	docs/en/01-design/architecture.md	对应目录层级一致

即中文目录名（如 01-设计）与英文目录名（如 01-design）互为翻译，同级目录下的文件一一对应。

双语同步要求

要求	说明
内容一致	核心技术内容必须完全同步，不得有差异
同步更新	中文更新后，英文版本需在 7 天内同步
标注差异	若中文有本土化补充内容，需在英文版标注

实际维护中，英文版通常以某个基准版本为主（docs/en/README.md 顶部注明其英文文档面向 v0.72 设计，最新版本以中文文档为准），因此中英两版在版本号上可能存在短暂差异，这正是「标注差异」规范存在的原因——当英文版无法及时跟上最新版本时，应在文档头部显式标注待同步状态。

新增文档流程

1. 先编写中文版，存放于 docs/zh-cn/对应目录/
2. 同步创建英文版，存放于 docs/en/对应目录/
3. 更新两份 README.md 导航，添加新文档链接
4. 在 PR 中说明双语同步情况

导航更新的具体位置可参考 docs/zh-cn/06-社区/README.md：其「文档导航」表格列出了 roadmap.md、开发者文档共建指南.md、社区规范/ 三条条目，每条包含序号、文档、说明、使用场景四列；英文对应版 docs/en/06-community/README.md 则列出 roadmap.md 与 documentation-contribution-guide.md 两条。

四、文档分类判定标准

按开发者旅程分类

新增文档时，先按以下标准判定归属目录：

旅程阶段	判定标准	归属目录
设计	接口规格、架构原理、通信机制、技术规划	01-design
开发	环境搭建、功能开发、组件定制、开发指南	02-development
调测	调试工具、问题定位方法、FAQ、排错指南	03-debugging
调优	性能优化方法、优化实践案例、性能分析	04-optimization
运维	版本管理、稳定性管理、构建打包、历史修复归档	05-operations
社区	社区规范、共建指南、路线图、贡献流程	06-community

例如仓库中 docs/zh-cn/05-运维/AI辅助问题定位指导.md 属于问题定位/运维场景，故归入 05-运维；docs/zh-cn/06-社区/社区规范/ 下收录了 社区issue管理规范.md、社区commit和pr规范.md、社区changelog规范.md、仓库分支管理规范.md、rnoh包管理规范.md、开发者共建指南.md 六类社区规范，全部归入 06-社区，符合「社区规范相关 → 06-社区」的判定标准。

版本相关性判定

在确定旅程目录后，需进一步判定文档是否版本相关：

标准	版本相关	示例
含版本号	✅	版本升级指导.md
SDK 版本依赖	✅	SDK版本配置指导.md
API 版本变更	✅	RN升级需要开发者适配整理.md
发布记录	✅	release-notes/
历史修复归档	✅	0.82稳定性修复汇总/（英文对应 0.82-stability-fixes/）
原理方法	❌	架构介绍.md、调试调测.md
规范标准	❌	社区issue管理规范.md

仓库佐证：05-运维 目录下 docs/zh-cn/05-运维/稳定版本识别与安装.md、docs/zh-cn/05-运维/版本说明.md、docs/zh-cn/05-运维/版本升级指导.md 均在 README 中被 ⚡ 标注为版本相关；docs/zh-cn/05-运维/release-notes/ 存放各版本详细发布说明（如 react-native-harmony-v0.86.1.md，英文对应 docs/en/05-operations/release-notes/）；docs/zh-cn/05-运维/稳定性历史修复/ 按版本归档修复记录（0.72/0.77/0.82 三个子目录）。而 docs/zh-cn/01-设计/架构介绍.md、docs/zh-cn/03-调测/调试调测.md 属于原理与方法类，长期有效，不随版本变化。

五、文档提交流程

提交前检查清单

检查项	说明
旅程目录	文档是否存放于正确的旅程目录
版本标识	版本相关文档是否标注适用版本
文件命名	是否符合命名规范
双语同步	是否同步创建/更新英文版本
导航更新	是否更新 README.md 导航
链接有效	内部链接是否可正常跳转
图片路径	图片引用路径是否正确

PR 提交规范

1. 标题格式：docs: 新增/更新/修复 [旅程阶段] [文档名称]

示例：

• docs: 新增 开发 多屏适配指导文档
• docs: 更新 运维 版本升级指导 v0.82 补充
• docs: 修复 调测 FAQ链接错误

这一标题格式与仓库的 commitlint 校验规则相吻合：仓库根目录的 commitlint.config.js 依赖 .quality-toolkit 提供的 type-enum 规则，docs 是合法的 commit type 之一；同时 docs/zh-cn/06-社区/社区规范/社区commit和pr规范.md 明确 docs type 对应 Changelog 的 Documentation 类型，即「文档变更（新增教程、补全 API 文档、勘误等）」。因此 docs: 前缀的 PR 标题既符合提交规范，也能被自动化工具识别并计入 Changelog。

2. 描述模板：

## 变更说明

- [新增/更新/修复] 文档：xxx
- 开发者旅程：设计 / 开发 / 调测 / 调优 / 测试 / 运维 / 社区
- 版本相关：是 / 否
- 双语同步：已同步英文版本 / 待同步

## 检查清单

- [x] 旅程目录正确
- [x] 版本标识完整
- [x] 文件命名规范
- [x] 双语同步完成
- [x] README 导航更新
- [x] 链接路径有效

3. 关联 Issue：如有相关 Issue，需在 PR 中关联。仓库对 Issue 协作另有 docs/zh-cn/06-社区/社区规范/社区issue管理规范.md 专门规范，包含 P0/P1/P2/P3 四级 SLA（首次响应时间从 12 小时到 48 小时不等）以及「提交 → 受理 → 处理 → 验收 → 关闭」的完整生命周期，文档类反馈通常按 P2 或 P3 处理。

发版后的文档同步

文档共建不仅包括新增与更新，还包括发版后的版本号同步。仓库在 docs/zh-cn/05-运维/README.md 中推荐使用文档版本同步 Skill（.agents/skills/rnoh-upgrade-version/rnoh-docs-version-upgrade/SKILL.md）在发版后更新整个 docs/ 的版本号与双语文档；docs/zh-cn/README.md 的「贡献指南」同样提到可通过 @.agents/skills/rnoh-upgrade-version/rnoh-docs-version-upgrade/SKILL.md 触发该流程。此外 .agents/skills/rnoh-upgrade/SKILL.md 还处理 docs/Samples 中 package.json 与 hvigor 插件 tgz 引用的版本号提升，属于发版维护链路的配套能力。

六、文档审核标准

审核维度

维度	标准
准确性	技术内容准确无误，代码示例可运行
完整性	内容覆盖完整，无关键信息遗漏
规范性	符合命名、格式、双语同步规范
可读性	结构清晰，语言简洁，易于理解
时效性	版本相关文档信息为最新版本
旅程匹配	文档内容与所属旅程目录匹配

审核流程

1. 提交者自查 → 检查清单全部通过
2. 社区审核 → 至少 1 位文档审核者通过
3. 合并 → 审核通过后合并到主分支

仓库对文档质量还提供了自动化辅助手段：.agents/skills/ 下存在 docs-quality-audit（文档质量审计）与 docs-spellcheck（文档拼写检查）两个 Skill（分别软链至 .quality-toolkit/skills/ 对应目录），提交者在自查阶段即可借助它们对文档做质量与拼写预检，降低人工审核返工概率。提交代码侧的规范（分支管理、Commit 格式、Changelog 联动）可进一步参考 docs/zh-cn/06-社区/社区规范/仓库分支管理规范.md 与 docs/zh-cn/06-社区/社区规范/开发者共建指南.md。

七、常见问题（FAQ）

Q1：如何判断文档应该放在哪个目录？

按开发者旅程判定：

• 设计阶段产出 → 01-design
• 开发过程所需 → 02-development
• 调试排错相关 → 03-debugging
• 性能优化相关 → 04-optimization
• 版本运维相关 → 05-operations
• 社区规范相关 → 06-community

Q2：英文版暂时无法同步怎么办？

在 PR 中标注「待同步」，并在中文文档头部添加：

> 英文版本待同步，欢迎社区贡献翻译

Q3：图片如何存放？

存放于文档同级或上级的 figures/ 目录，使用相对路径引用：

<a href="https://link.gitcode.com/i/0f997978dc91a396550fcde5f1b83627" target="_blank">![示例图片](https://raw.gitcode.com/CPF-RN/ohos_react_native/raw/37c3af8e8734950349cf77f6756a17a8255d74f2/docs/en/figures/example.png?utm_source=gitcode_repo_files)</a>

仓库各阶段目录下的图片即统一存放在对应 figures/ 中，例如 docs/zh-cn/figures/ 与 docs/en/figures/ 分别集中存放中英文文档所需的架构图、运行截图与 FAQ 示意图。

Q4：如何更新 README 导航？

在对应语言目录的 README.md 中：

1. 在「开发者旅程导航」表格添加新条目
2. 在「目录结构」树形图添加文件位置

参考 docs/zh-cn/06-社区/README.md：其「文档导航」表格每个条目含序号、文档、说明、使用场景四列，「目录结构」则以树形图展示 06-社区/ 下的 roadmap.md、开发者文档共建指南.md、社区规范/ 等位置。

Q5：版本相关文档更新时机？

文档类型	更新时机
版本说明	版本发布当天
升级指导	版本发布当天
SDK 配置	SDK 版本变更时
历史修复	版本发布后一周内归档

仓库实况与之对应：docs/zh-cn/05-运维/release-notes/ 下已存在 react-native-harmony-v0.86.1.md 等发布说明文件；docs/zh-cn/05-运维/稳定性历史修复/ 按版本归档了 0.72、0.77、0.82 的稳定性修复汇总，符合「发布后一周内归档」的节奏。

八、贡献者激励

贡献类型	认证方式
新增核心文档	文档署名 + 社区贡献者认证
双语同步贡献	翻译贡献者认证
文档持续维护	文档维护者认证
版本文档及时更新	版本维护者认证

附录：目录结构速查表

目录	旅程阶段	版本相关	核心内容
01-design	设计	❌	架构、原理、接口规格
02-development	开发	✅ 部分	环境、功能、组件、场景
03-debugging	调测	❌	调试、定位、FAQ
04-optimization	调优	❌	性能、实践案例
05-operations	运维	✅	版本、构建、稳定性、修复归档
06-community	社区治理	❌	规范、路线图

如有疑问，请在社区 Issue 中提出，或联系文档维护者。参与社区共建前，可先阅读 docs/zh-cn/06-社区/roadmap.md 了解版本规划，再按本文规范提交文档变更。