本指南面向参与 RNOH 社区文档共建的开发者，规范文档编写、分类、双语同步与提交流程，确保文档质量统一、维护高效。

---

一、文档目录结构

文档按 开发者旅程 组织，覆盖从设计到运维的全生命周期：

目录与开发者旅程对应

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

版本相关文档标识

以下文档需随版本发布同步更新：

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

---

二、文档编写规范

文件命名规范

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

示例：

• 中文：版本升级指导.md、调试调测.md
• 英文：version-upgrade-guide.md、debugging.md

文档头部模板

每个文档开头必须包含以下元信息：

# 文档标题

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

## 概述

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

内容编写要求

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

---

三、双语文档处理规范

双语文件对应规则

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

双语同步要求

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

新增文档流程

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

---

四、文档分类判定标准

按开发者旅程分类

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

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

版本相关性判定

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

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

---

五、文档提交流程

提交前检查清单

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

PR 提交规范

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

   示例：

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

2. 描述模板：

   ## 变更说明
   
   - [新增/更新/修复] 文档：xxx
   - 开发者旅程：设计 / 开发 / 调测 / 调优 / 测试 / 运维 / 社区
   - 版本相关：是 / 否
   - 双语同步：已同步英文版本 / 待同步
   
   ## 检查清单
   
   - [x] 旅程目录正确
   - [x] 版本标识完整
   - [x] 文件命名规范
   - [x] 双语同步完成
   - [x] README 导航更新
   - [x] 链接路径有效
   

3. 关联 Issue：如有相关 Issue，需在 PR 中关联

---

六、文档审核标准

审核维度

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

审核流程

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

---

七、常见问题

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

按开发者旅程判定：

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

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

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

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

Q3：图片如何存放？

存放于文档同级或上级的 figures/ 目录：

![示例图片](../figures/example.png)

Q4：如何更新 README 导航？

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

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

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

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

---

八、贡献者激励

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

---

附录：目录结构速查表

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

---

如有疑问，请在社区 Issue 中提出，或联系文档维护者。