编写文档

面向需要使用或开发本移植项目的读者写作。先说明功能的作用，再展示用法，最后解释与任务有关的设置。

组织页面

使用简短的介绍和明确的标题。操作流程采用编号步骤，例如“安装工具”“构建镜像”和“烧录开发板”。先说明命令的用途，再给出命令，随后描述读者应看到的结果或下一步操作。

参考页可以用表格列出选项、限制和返回值。将实现细节放在使用示例之后，让读者无需先读驱动设计就能开始使用。

语气与措辞

使用清晰、自然的语言。需要时用“你”称呼读者，并采用工具中显示的名称。例如：

要启用 I2C0，运行 s31-overlay apply i2c0。该选择会被保存，并在启动时恢复。

在限制会影响选择或命令的地方说明限制。烧录警告应放在烧录命令旁；传输大小限制应放在外设参考中。已有说明可通过链接引用，无需在每一页重复背景或警告。

示例

说明命令是在主机还是开发板上运行。使用中性的示例名称，并解释读者需要替换的值。示例中不要包含密码和私钥。

修改行为描述之前，先搜索实现及其调用者、配置或测试。例如，对命令检查参数解析器、处理函数和用法测试；对构建选项检查赋值位置，以及它如何影响最终配置。在精确的接口约定或限制旁链接相关源码。区分源码检查与成功的硬件运行；声称经过测试时，应链接注明日期的运行记录。

先展示常规流程，再介绍可选配置和故障排查。安装兼容工具需要时可以注明版本；详细测试历史应放在链接的测试报告中。

将页面加入指南

页面是 en/ 和 zh_CN/ 下的 Markdown 文件，两种语言采用相同的相对路径。修改命令、限制或流程时，同步更新两个版本。翻译正文和标题，保留可执行示例、标识符和命令输出。链接到译文标题不同的章节时，使用两种语言共用的显式标签。在标题前用 (shared-label)= 定义标签，然后通过 [section title](shared-label) 链接；page.md#heading-slug 使用的是标题文字生成的锚点，而非显式标签。

将新页面加入两种语言中相应章节的 toctree，使其出现在导航中。每页只设置一个 toctree 父级，其他相关页面通过普通链接引用。链接到本指南的其他页面时，优先使用相对 Markdown 链接。

尽量保留现有页面路径。指南或主 README 仍在引用的图片应予以保留。

预览修改

在文档仓库中，将 requirements.txt 中的依赖安装到 Python 虚拟环境，然后运行：

make html SPHINXOPTS="-W --keep-going"
python3 -m http.server --bind 127.0.0.1 --directory build/html 8000

打开 http://127.0.0.1:8000/，检查两种语言中修改后的页面、导航、表格、搜索结果和代码示例。完成后按 Ctrl+C 停止服务器。提交改动前，检查外部链接：

make linkcheck SPHINXOPTS="-W --keep-going"

make html 分别以 language=en 和 language=zh_CN 运行 Sphinx，再构建语言入口页。因此，生成的导航和搜索界面也会采用相应语言。

语言下拉菜单由 sphinx_rtd_theme 提供。在 GitHub Pages 上，conf.py 将本地译文 URL 提供给主题的下拉菜单渲染器；在 Read the Docs 上则由托管服务提供数据。应从深层页面和搜索页检查语言切换，并确认每种语言的侧栏只包含该语言的内容。如果行为发生变化，应同步更新相关使用指南和参考页。