diff --git a/zh-cn/contribute/template/guide-template.md b/zh-cn/contribute/template/guide-template.md index 44238407230ec355d457f70dd4c37943fa3073b9..fefe1359814200857ff975c45e75bde193658251 100644 --- a/zh-cn/contribute/template/guide-template.md +++ b/zh-cn/contribute/template/guide-template.md @@ -2,18 +2,19 @@ > **注意:** -> _1、本模板提供推荐的开发指南文档框架、典型知识点写作要求及写作指导。实际写作中,应视具体__方案/特性/功能/模块__情况,先完成开发者任务场景分析与开发指南大纲设计,然后参照本模板写作具体内容。_ > -> _2、文档写作时,两级标题之间的位置不允许添加内容。_ +> _1、本模板提供推荐的开发指南文档框架、典型知识点写作要求及写作指导。实际写作中,应视具体**方案/特性/功能/模块**情况,先完成开发者任务场景分析与开发指南大纲设计,然后参照本模板写作具体内容。_ +> +> _2、文档写作时,一级标题与二级标题之间的位置不允许添加内容。_ > > _3、所有斜体为写作指导,正式文档中注意全部删除。_ ## xxx概述 -_必选。根据具体__方案/特性/功能/模块__的场景划分情况,此处的“xxx概述”与具体任务场景下的“任务场景n概述”按需提供一处或共存,具体的:_ +_必选。根据具体**方案/特性/功能/模块**情况的场景划分情况,此处的“xxx概述”与具体任务场景下的“任务场景n概述”按需提供一处或共存,具体的:_ -_1、此处的“xxx概述”":用于承载开发者需要了解的、本特性各任务场景通用的概述内容。如无,则删除。_ +_1、此处的“xxx概述”:用于承载开发者需要了解的、本特性各任务场景通用的概述内容。如无,则删除。_ _2、“任务场景n概述”:用于承载任务场景n直接相关的概述内容,知识点构成及写作要点与“xxx概述”相同,包括任务场景n简介、任务场景n直接相关的基本概念、任务场景n直接相关的实现原理、任务场景n直接相关的约束与限制、任务场景n直接相关的相关实例。如无,则删除。_ @@ -21,11 +22,11 @@ _2、“任务场景n概述”:用于承载任务场景n直接相关的概述 **_1、目标对象:_**_面向内、外部开发者(含产品经理、开发人员)。面向UX设计师的指导文档通常由专门的UX设计规范承载,不在开发指南范畴。本文如需提及,以超链接方式指向对应UX规范即可。_ -_**2、内容定位:**介绍__方案/特性/功能/模块__是什么(What)、能做什么(Why),以及如何进行相关应用程序/设备的设计、开发、发布上架(How)。支撑开发者学习必要知识,最终在实际开发活动中完成既定任务目标。_ +**_2、内容定位:_**_介绍**方案/特性/功能/模块**是什么(What)、能做什么(Why),以及如何进行相关应用程序/设备的设计、开发、发布上架(How)。支撑开发者学习必要知识,最终在实际开发活动中完成既定任务目标。_ -_**3、用户视角:**变身开发者,始终以开发者视角,提供开发者关注的、可感知和使用的内容。_ +**_3、用户视角:_**_变身开发者,始终以开发者视角,提供开发者关注的、可感知和使用的内容。_ -_**4、面向任务:**聚焦开发者实际任务,完整、正确、易用,具备权威指导性。_ +**_4、面向任务:_**_聚焦开发者实际任务,完整、正确、易用,具备权威指导性。_ _5、不要受限:模板只是基础框架,不要僵化。_ @@ -40,7 +41,7 @@ _这个方案/特性/功能/模块是什么(定义-what)?我为什么要 _**【写作要点】**_ -- _提供易理解的场景化描述。__可参考如下SCQA方式介绍方案/特性/功能/模块客户面的功能场景、特点。_ +- _提供易理解的场景化描述。_ _可参考如下SCQA方式介绍方案/特性/功能/模块客户面的功能场景、特点。_ - _S:situation(情景),由大家都熟悉的的情景、事实引入。_ - _C:complication(冲突),但是实际情况往往和我们的要求有冲突。_ - _Q:question(疑问),怎么办?_ @@ -71,7 +72,7 @@ _要使用该方案/特性/功能/模块,有哪些独有概念是我需要了 - _运作机制、约束限制、开发过程等多个章节相关的概念在此介绍,仅某个章节用到的概念在对应章节中介绍。_ -- _业界通用的概念不用在此赘述。__注意使用业界通用术语来表达,不用华为研发内部语言。_ +- _业界通用的概念不用在此赘述。_ _注意使用业界通用术语来表达,不用华为研发内部语言。_ - _概念之间如有逻辑关系,推荐使用图形描述。_ @@ -141,7 +142,7 @@ _可选。此处放置以下各任务场景通用的约束与限制。_ _**【开发者关注点】**_ -_我要__使用该方案/特性/功能/模块,有什么约束条件吗?__该方案/特性/功能/模块__实现的程度如何,能满足我的需求吗?_ +_我要使用该方案/特性/功能/模块,有什么约束条件吗?该方案/特性/功能/模块实现的程度如何,能满足我的需求吗?_ **_【写作要点】_** @@ -174,7 +175,7 @@ _有哪些Sample code、Codelabs、Demo工程可供学习、参考。_ **_【写作要点】_** -_已发布的Sample code、Codelabs、Demo工程包,请在此处提供链接(一般为Gitee链接)。__注意:不允许将工程包等作为附件插入到文档中。_ +_已发布的Sample code、Codelabs、Demo工程包,请在此处提供链接(一般为Gitee链接)。_ _注意:不允许将工程包等作为附件插入到文档中。_ **【写作样例】** @@ -189,7 +190,7 @@ _可选。_ _根据具体的开发场景分析分解情况,本节内容可按需放入“开发指导”下,作为“前提条件”或“开发准备”与具体场景的“开发步骤”就近放置。_ -_明确如何准备开发环境(如软硬件配置要求、工具要求、设备要求等)__。_ +_明确如何准备开发环境(如软硬件配置要求、工具要求、设备要求等)。_ _如果不涉及上述特殊要求,此章节删除。_ @@ -256,7 +257,7 @@ _贴近开发者实际开发场景:_ - _开发者需要通过哪些任务来达成开发目标,这就是任务场景。_ -- _任务场景可以有1个或多个,__可按需添加多个“开发指导”章节。__同时要遵循分层分级逻辑,即大场景(任务场景n)->小场景(子任务场景n-x)->任务逻辑(对应“开发流程”)->操作步骤(一个个step)。_ +- _任务场景可以有1个或多个,可按需添加多个“开发指导”章节。同时要遵循分层分级逻辑,即大场景(任务场景n)->小场景(子任务场景n-x)->任务逻辑(对应“开发流程”)->操作步骤(一个个step)。_ ### 任务场景n概述