From e29910bd78a7194f956af73d9a1b04824f255c9e Mon Sep 17 00:00:00 2001
From: zhangxiaowei16 <zhangxiaowei16@xiaomi.com>
Date: Fri, 3 Jan 2025 15:16:18 +0800
Subject: [PATCH 1/2] Add developer documentation template

---
 zh-cn/contribute/template/README-template.md  |  97 +++++++
 zh-cn/contribute/template/concept_template.md |  25 ++
 .../template/development_guide_template.md    | 249 ++++++++++++++++++
 zh-cn/contribute/template/faq_template.md     |  40 +++
 .../template/operation_guide-template.md      | 158 +++++++++++
 5 files changed, 569 insertions(+)
 create mode 100644 zh-cn/contribute/template/README-template.md
 create mode 100644 zh-cn/contribute/template/concept_template.md
 create mode 100644 zh-cn/contribute/template/development_guide_template.md
 create mode 100644 zh-cn/contribute/template/faq_template.md
 create mode 100644 zh-cn/contribute/template/operation_guide-template.md

diff --git a/zh-cn/contribute/template/README-template.md b/zh-cn/contribute/template/README-template.md
new file mode 100644
index 0000000..28d7e4c
--- /dev/null
+++ b/zh-cn/contribute/template/README-template.md
@@ -0,0 +1,97 @@
+# xxx系统/模块
+
+> **注意：**
+>
+> _1、本模板提供推荐的README写作指导。_
+>
+> _2、所有斜体为写作指导，正式文档中注意全部删除。_
+
+**_【总体写作要求】_**
+
+**_1、确认写作内容：_**_介绍**系统/模块**是什么（What）、能做什么（Why），以及如何进行开发（How）。_
+
+**_2、变身用户视角：_**_以开发者视角，提供开发者关注的和需要使用的内容。_
+
+**_3、不要受限：_**_模板供参考，根据实际情况灵活调整。_
+
+## 简介
+
+_【写作要求】**必选**_
+
+_**内容介绍:**在整个 openvela 架构中的作用、实现的功能、使用场景、支持的设备等。_
+
+_**注意事项如下:**_
+
+| 要求项 | 内容要求 |
+| -------- | -------- |
+| **1** | **用语要求** |
+| 1.1 | 行文风格：用语正式，避免口语化。 |
+| 1.2 | 合规要求：不能使用第三方知识产权特有概念等存在合规和法务风险的词汇。 |
+| 1.3 | 用语一致：术语与术语库保持一致，正文中缩略语首次出现要给出全称。 |
+| **2** | **格式要求** |
+| 2.1 | 标点符号正确，一句话结束以句号结尾。 |
+| 2.2 | 内容尽量用项目列表或分类的方式清晰呈现。|
+| 2.3 | 如果是内容的辅助说明，请使用“说明/注意/警告”式样。 |
+| **3** | **表格** |
+| 3.1 | 表格有表头，表格无内容用“不涉及/无”，不出现空白的单元格。 |
+| **4** | **截图** |
+| 4.1 | 图形逻辑清晰，图文配合使用。 |
+| 4.2 | 建议为.png格式。 |
+| 4.3 | 中文图用中文，英文图用英文。 |
+
+## 架构图
+
+_【写作要求】**可选**_
+
+| 要求项 | 内容要求 |
+| -------- | -------- |
+| 1 | 使用架构图说明该系统/模块架构，对架构中的主要组成部分进行必要的解释说明。 |
+| 2 | 如果本模块只是子系统的一部分，需要理解子系统相关概念，给出**请参考xxx**。 |
+
+## 代码目录
+
+_【写作要求】  **必选** ，**明确本项目仓的代码**目录结构**以及对应目录的**功能描述。_
+
+```tree
+├── include                 # 框架代码
+│   ├── tapi_call.h         # 头文件目录
+│   ├── tapi_cbs.h
+├── src
+│   ├── tapi_call.c
+│   ├── tapi_cbs.c
+│   └── tapi_utils.c        # 工具类
+├── tools
+│   └── telephony_tool.c
+```
+
+## 使用限制
+
+_【写作要求】  **可选**，明确子系统运行的必要条件，如指定操作系统的固定版本。_
+
+| 要求项 | 内容要求 |
+| -------- | -------- |
+| 1 | 明确功能限制或操作限制。 |
+| 2 | 约束对指导任务开发有影响。 |
+
+## 使用说明
+
+_【写作要求】  **可选**_
+
+| 要求项 | 内容要求 |
+| -------- | -------- |
+| **1** | **如何写好步骤** |
+| 1.1 | 步骤完整：提供必需的步骤，保证操作可顺利完成。 |
+| 1.2 | 任务句式：使用“动词+名词”句式。 |
+| 1.3 | 明确目的：明确该步骤的目的，即想达成什么目标。 |
+| 1.4 | 步骤执行完成后，给出操作是否成功的标准。 |
+| **2** | **如何写好代码段** |
+| 2.1 | 确保代码正确可执行。 |
+| 2.2 | 关键步骤有清晰的注释说明。 |
+
+## 效果预览
+
+_【写作要求】  **可选**，使用该模块的效果，可以使用截屏或者视频。_
+
+## 相关仓
+
+_【写作要求】  **可选**，列出和当前系统/模块有强相关的关联仓链接，方便开发者进一步深入学习。_
diff --git a/zh-cn/contribute/template/concept_template.md b/zh-cn/contribute/template/concept_template.md
new file mode 100644
index 0000000..da936de
--- /dev/null
+++ b/zh-cn/contribute/template/concept_template.md
@@ -0,0 +1,25 @@
+# 所要解释的概念名称
+
+> **注意：**
+>
+> _1、本模板提供推荐的概念类文档写作指导。_
+>
+> _2、所有斜体为写作指导，正式文档中注意全部删除。_
+
+## 概述
+
+_写作要求】**必选**_
+
+_**内容介绍**：使用一段文字概括当前主题的上下文。_
+
+## 正文
+
+_【写作要求】**必选**，文字+表格+图片三者结合进行讲解_
+
+## 使用示例
+
+_【写作要求】  **可选** ，提供一个与该概念相关的简单示例，辅助概念讲解。_
+
+## 后续操作
+
+_【写作要求】  **可选**，提供一个项目符号列表（最多 5 个），帮助读者进一步学习掌握概念。_
diff --git a/zh-cn/contribute/template/development_guide_template.md b/zh-cn/contribute/template/development_guide_template.md
new file mode 100644
index 0000000..73cd269
--- /dev/null
+++ b/zh-cn/contribute/template/development_guide_template.md
@@ -0,0 +1,249 @@
+# xxx子系统/模块开发指南
+
+> **说明：**
+>
+> _1、本模板提供开发指南文档写作模板，需先完成需求场景分析，然后参照本模板进行写作。_
+>
+> _2、斜体字为写作指导，正式文档中请删除。_
+
+**_【总体写作要求】_**
+
+**_1、明确目标受众：_**_明确开发者目标受众：开发人员/产品经理/架构师）。_
+
+**_2、确认写作内容：_**_介绍**功能/模块**是什么（What）、能做什么（Why），以及如何进行开发（How）。_
+
+**_3、变身用户视角：_**_以开发者视角，提供开发者关注的和需要使用的内容。_
+
+**_4、面向任务写作：_**_聚焦开发者需要完成的任务，具备指导性。_
+
+**_5、不要受限：_**_模板供参考，根据实际情况灵活调整。_
+
+## xxx（具体功能/模块名称）简介
+
+_必选。_
+
+_明确what、why等基础信息，帮助开发者建立对特性/功能/模块的初步认知。_
+
+_**【开发者关注点】**_
+
+_这个功能/模块是什么（定义-what）？它能解决什么问题或者带来什么收益？（客户价值-why）。_
+
+_**【写作要点】**_
+
+_参考场景化写作，使用如下 SCQA 方式介绍:_
+
+- _S：situation（情景），由大家都熟悉的的情景、事实引入。_
+- _C：complication（冲突），但是实际情况往往和我们的要求有冲突。_
+- _Q：question（疑问），How？_
+- _A：answer（回答），我们的解决方案是 …_
+
+**_【写作要求】_**
+
+- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_
+
+### 功能特性
+
+_可选。_
+
+_介绍该功能/模块关键开放能力，辅助选型。_
+
+_**【开发者关注点】**_
+
+_该功能/模块提供了哪些关键功能？_
+
+**_【写作要求】_**
+
+- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_
+
+### 优势
+
+_可选。_
+
+_介绍功能/模块相对业界类似能力的优势，辅助选型。_
+
+_**【开发者关注点】**_
+
+_该功能/模块有哪些优势？_
+
+**_【写作要点】_**
+
+- _明确有吸引力的优势，不要夸大。_
+
+**_【写作要求】_**
+
+- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_
+
+### 前置概念
+
+_可选。_
+
+_**【开发者关注点】**_
+
+_要使用该功能/模块，有哪些概念是首先需要了解的？_
+
+**_【写作要点】_**
+
+- _开发者需要完成本指南之前，需要了解的概念。_
+- _概念之间如有复杂逻辑关系，请补充画图进行介绍。_
+
+**_【写作要求】_**
+
+- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_
+
+_**【写作样例】**_
+
+_在使用云容器引擎前，开发者应了解以下基本概念：_
+
+- **Pod**
+
+  _容器组（Pod）是Kubernetes创建或部署的最小单位。_
+
+- **容器**
+
+  _容器技术起源于Linux，是一种内核虚拟化技术。_
+
+### 实现原理
+
+_可选。_
+
+_**【开发者关注点】**_
+
+_该功能/模块是如何工作的？了解其原理以更好的使用。_
+
+**_【写作要点】_**
+
+- _尽量图文结合，结合流程图架构图等。_
+
+- _不要泄密。_
+
+**_【写作要求】_**
+
+- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_
+
+### 使用限制
+
+_可选。_
+
+_**【开发者关注点】**_
+
+_使用该功能/模块，有什么限制吗？_
+
+**_【写作要点】_**
+
+- _描述对开发活动有影响的限制，样例如下：_
+  - **_功能限制_**
+    - _功能使用场景（哪些场景不支持）。_
+    - _规格限制。_
+
+**_【写作样例】_**
+
+- _XXX以上版本方可使用本功能。_
+
+- _每个对象大小不超过100KB。_
+
+### 与相关功能模块的关系
+
+_可选。_
+
+_有些功能/模块如有比较强的相关性赖，需在此补充明确。_
+
+**_【写作要点】_**
+
+- _尽量图文结合，结合架构图流程图等。_
+
+## 环境准备
+
+_可选。_
+
+_明确开发环境（如硬件要求、软件要求、操作系统要求等）。_
+
+### 搭建环境
+
+**_【写作要求】_**
+
+_搭建开发环境的具体步骤，使用step by step的方式进行写作。_
+_确给出环境搭建是否成功的检验标准。_
+
+_**【写作样例】**_
+
+1. 使用 SSH 方式登陆 Linux 服务器终端。
+
+2. 安装基础包，运行如下命令。
+
+   ```bash
+   xxxxx
+   ```
+
+3. 查看安装版本，运行如下命令。
+
+   ```C
+   xxxxx
+   ```
+
+## 开发流程
+
+**_【写作要点】_**
+
+_可选。_
+
+- _开发者要使用这个功能/模块，需要怎么做（how）？_
+
+- _遵循分层分级逻辑：场景（任务场景）-&gt;任务逻辑（开发流程）-&gt;操作步骤（step by step）。_
+
+- _当开发步骤较多，请提供流程图。_
+
+### 接口说明
+
+**_【写作要求】_**
+
+_可选。_
+
+- _描述以下开发步骤中有涉及哪些关键接口，可以链接的方式提供。_
+
+### 开发步骤
+
+**_【写作要求】_**
+
+_必选。_
+
+- _**每个步骤有清晰的执行主体（who），明确操作目的（why）、操作内容（what/how）、场景（when/where）。使用祈使句描述步骤。**_
+
+- _保证示例代码可执行。_
+
+- _开发完成后，需提供指导以确认操作是否成功。_
+
+- _涉及用户手机号码、身份证号、账号名等敏感信息均需要进行脱敏处理，例如：186********；涉及IP地址、域名等信息，需要使用私网IP或通用示例格式代替，例如：xx.xx.xx.xx、www.example.com，**禁止使用真实的IP地址或域名**。_
+
+### 相关实例
+
+_可选。_
+
+_场景通用的其他相关实例。_
+
+**_【开发者关注点】_**
+
+_有哪些 Sample code、Demo 可以进一步学习。_
+
+**_【写作要点】_**
+
+_已发布的 Sample code、Demo ，请在此处提供链接。_
+
+ ## 常见问题
+
+_可选。_
+
+**_【开发者关注点】_**
+
+_开发流程中可能遇到的问题。_
+
+**_【写作要点】_**
+
+_描述开发过程遇到的各类问题以及解决方案，以提高开发效率。_
+
+_具体写作模板请参见[《FAQ模板》](faq-template.md)。_
+
+## 后续操作
+
+**_【写作要点】_**
+
+_使用无序列表（不超过 5 项），列举开发者可能接下来有兴趣的主题。_
diff --git a/zh-cn/contribute/template/faq_template.md b/zh-cn/contribute/template/faq_template.md
new file mode 100644
index 0000000..ed8279f
--- /dev/null
+++ b/zh-cn/contribute/template/faq_template.md
@@ -0,0 +1,40 @@
+# FAQ写作模板
+
+__**FAQ = 问题现象 + 可能原因 + 处理措施**_
+
+_一般 FAQ 分为以下两类：_
+
+* _[问题处理](#一-问题处理)_
+* _[咨询](#二-咨询)_
+
+## 一 问题处理
+
+### 问题标题
+
+_必选。_
+
+_一句话描述问题的现象，需要考虑到开发者使用哪些关键字进行搜索。_
+
+#### 问题现象
+
+_可选。_
+
+_描述开发者可能遇到的报错，例如问题出现的场景现象等。_
+
+#### 可能原因
+
+_可选。_
+
+_明确问题产生的原因。_
+
+#### 解决措施
+
+_step by step 方式写作，保证可执行性。_
+
+## 二 咨询
+
+### 咨询标题
+
+_以开发者的疑问点切入，注意包含关键词以方便搜索。_
+
+_可提供指南/API参考等资料链接，方便开发者深入理解。_
\ No newline at end of file
diff --git a/zh-cn/contribute/template/operation_guide-template.md b/zh-cn/contribute/template/operation_guide-template.md
new file mode 100644
index 0000000..30939b5
--- /dev/null
+++ b/zh-cn/contribute/template/operation_guide-template.md
@@ -0,0 +1,158 @@
+# xxx操作（建议动词+名词形式）
+
+> **注意：**
+>
+> _1、本模板提供推荐的操作指南文档框架写作指导。_
+>
+> _2、所有斜体为写作指导，正式文档中注意全部删除。_
+
+**_【总体写作要求】_**
+
+**_1、明确目标受众：_**_明确开发者目标受众：开发人员/产品经理/架构师）。_
+
+**_2、确认写作内容：_**_介绍**功能/模块**是什么（What）、能做什么（Why），以及如何进行开发（How）。_
+
+**_3、变身用户视角：_**_以开发者视角，提供开发者关注的和需要使用的内容。_
+
+**_4、面向任务写作：_**_聚焦开发者需要完成的任务，具备指导性。_
+
+**_5、不要受限：_**_模板供参考，根据实际情况灵活调整。_
+
+## 概述
+
+_必选。_
+
+_明确what、why等基础信息，帮助开发者建立对特性/功能/模块的初步认知。_
+
+_**【开发者关注点】**_
+
+_这个功能/模块是什么（定义-what）？它能解决什么问题或者带来什么收益？（客户价值-why）。_
+
+_**【写作要点】**_
+
+_参考场景化写作，使用如下 SCQA 方式介绍:_
+
+- _S：situation（情景），由大家都熟悉的的情景、事实引入。_
+- _C：complication（冲突），但是实际情况往往和我们的要求有冲突。_
+- _Q：question（疑问），How？_
+- _A：answer（回答），我们的解决方案是 …_
+
+**_【写作要求】_**
+
+- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_
+
+## 前提条件
+
+_必选。_
+
+_列出用户在执行本指南中的步骤之前要做的一切，推荐使用**无序列表**的形式_
+
+## 前置概念
+
+_可选。_
+
+_**【开发者关注点】**_
+
+_要使用该功能/模块，有哪些概念是首先需要了解的？_
+
+**_【写作要点】_**
+
+- _开发者需要完成本指南之前，需要了解的概念。_
+- _概念之间如有复杂逻辑关系，请补充画图进行介绍。_
+
+**_【写作要求】_**
+
+- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_
+
+## 实现原理
+
+_可选。_
+
+_**【开发者关注点】**_
+
+_该功能/模块是如何工作的？了解其原理以更好的使用。_
+
+**_【写作要点】_**
+
+- _尽量图文结合，结合流程图架构图等。_
+
+- _不要泄密。_
+
+**_【写作要求】_**
+
+- _仅使用必要的术语、缩略语或专有名词，并给出解释（提供到术语表链接也可以）。_
+
+## 使用限制
+
+_可选。_
+
+_**【开发者关注点】**_
+
+_使用该功能/模块，有什么限制吗？_
+
+**_【写作要点】_**
+
+- _描述对开发活动有影响的限制，样例如下：_
+  - **_功能限制_**
+    - _功能使用场景（哪些场景不支持）。_
+    - _规格限制。_
+
+**_【写作样例】_**
+
+- _XXX以上版本方可使用本功能。_
+
+- _每个对象大小不超过100KB。_
+
+## 环境准备
+
+_可选。_
+
+_明确开发环境（如硬件要求、软件要求、操作系统要求等）。_
+
+## 操作流程
+
+**_【写作要点】_**
+
+_可选。_
+
+- _开发者要使用这个功能/模块，需要怎么做（how）？_
+
+- _遵循分层分级逻辑：场景（任务场景）-&gt;任务逻辑（开发流程）-&gt;操作步骤（step by step）。_
+
+- _当开发步骤较多，请提供流程图。_
+
+## 操作步骤
+
+**_【写作要求】_**
+
+**_【写作要求】_**
+
+_必选。_
+
+- _**每个步骤有清晰的执行主体（who），明确操作目的（why）、操作内容（what/how）、场景（when/where）。使用祈使句描述步骤。**_
+
+- _保证示例代码可执行。_
+
+- _开发完成后，需提供指导以确认操作是否成功。_
+
+- _涉及用户手机号码、身份证号、账号名等敏感信息均需要进行脱敏处理，例如：186********；涉及IP地址、域名等信息，需要使用私网IP或通用示例格式代替，例如：xx.xx.xx.xx、www.example.com，**禁止使用真实的IP地址或域名**。_
+
+## 常见问题
+
+_可选。_
+
+**_【开发者关注点】_**
+
+_开发流程中可能遇到的问题。_
+
+**_【写作要点】_**
+
+_描述开发过程遇到的各类问题以及解决方案，以提高开发效率。_
+
+_具体写作模板请参见[《FAQ模板》](faq-template.md)。_
+
+## 后续操作
+
+**_【写作要点】_**
+
+_使用无序列表（不超过 5 项），列举开发者可能接下来有兴趣的主题。_

From b9ec7641335ed965395aeea51e33913a6fb10119 Mon Sep 17 00:00:00 2001
From: zhangxiaowei16 <zhangxiaowei16@xiaomi.com>
Date: Fri, 3 Jan 2025 16:37:11 +0800
Subject: [PATCH 2/2] Add developer documentation template

---
 zh-cn/contribute/template/README-template.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/zh-cn/contribute/template/README-template.md b/zh-cn/contribute/template/README-template.md
index 28d7e4c..c1942c9 100644
--- a/zh-cn/contribute/template/README-template.md
+++ b/zh-cn/contribute/template/README-template.md
@@ -88,9 +88,10 @@ _【写作要求】  **可选**_
 | 2.1 | 确保代码正确可执行。 |
 | 2.2 | 关键步骤有清晰的注释说明。 |
 
-## 效果预览
 
-_【写作要求】  **可选**，使用该模块的效果，可以使用截屏或者视频。_
+## 接口说明
+
+_【写作要求】 **可选**，提供本仓库提供的API接口链接。_
 
 ## 相关仓