harmony 鸿蒙开发指南写作模板
开发指南写作模板
修订记录
修改描述 | 日期 |
---|---|
开发指南按照Kit粒度提供,本模板相应刷新。 | 2024⁄03 |
注意:
1、本模板提供推荐的开发指南文档框架、典型知识点写作要求及写作指导。实际写作中,应视具体Kit/方案/特性/功能/模块情况,先完成开发者任务场景分析与开发指南大纲设计,然后参照本模板写作具体内容。
2、文档写作时,一级标题与二级标题之间的位置不允许添加内容。
3、所有斜体为写作指导,正式文档中注意全部删除。
【开发指南总体写作要求】
1、目标对象:面向内、外部开发者(含产品经理、开发人员)。面向UX设计师的指导文档通常由专门的UX设计规范承载,不在开发指南范畴。本文如需提及,以超链接方式指向对应UX规范即可。
2、内容定位:介绍Kit/方案/特性/功能/模块是什么(What)、能做什么(Why),以及如何进行相关应用程序/设备的设计、开发、发布上架(How)。支撑开发者学习必要知识,最终在实际开发活动中完成既定任务目标。
3、用户视角:变身开发者,始终以开发者视角,提供开发者关注的、可感知和使用的内容。
4、面向任务:聚焦开发者实际任务,完整、正确、易用,具备权威指导性。
5、不要受限:模板只是基础框架,不要僵化。
6、关于仅面向系统应用开放的内容:对于仅面向系统应用开放的内容,在概念、原理、开发场景等各处,均建议做topic级隔离,即独立md承载,且标题显性标识“仅对系统应用开放”。
xxx(使用具体Kit/方案/特性/功能/模块名称替代)简介
必选。开篇先阐明what、why、when基础信息,让开发者对Kit/方案/特性/功能/模块有初步认知。
【开发者关注点】
这个Kit/方案/特性/功能/模块是什么(定义-what)?我为什么要用它?它能解决哪些问题或带来哪些收益?(目的/客户价值-why)
【写作要点】
提供易理解的场景化描述。 可参考如下SCQA方式介绍Kit/方案/特性/功能/模块客户面的功能场景、特点。
- S:situation(情景),由大家都熟悉的的情景、事实引入。
- C:complication(冲突),但是实际情况往往和我们的要求有冲突。
- Q:question(疑问),怎么办?
- A:answer(回答),我们的解决方案是 …
抽象的概念要具象化,可以适当引入2C视角(如UX中的场景效果)的内容,帮助理解。
【写作要求】
清晰易懂,避免模糊、晦涩、有歧义的表述。
仅使用必要的术语、缩略语或专有名词,并给出解释(提供到术语表链接也可以)。
文中使用的术语、缩略语或专有名词应全文保持一致。
【写作样例】
Form Kit(卡片开发服务)提供一种界面展示形式,可以将应用的重要信息或操作前置到服务卡片(以下简称“卡片”),以达到服务直达、减少跳转层级的体验效果。卡片常用于嵌入到其他应用(当前被嵌入方即卡片使用方只支持系统应用,例如桌面)中作为其界面显示的一部分,并支持拉起页面、发送消息等基础的交互能力。
能力范围
可选。介绍Kit/方案/特性/功能/模块关键开放能力,支撑选型。
【开发者关注点】
该Kit/方案/特性/功能/模块提供了哪些关键开放能力?我要不要使用它?
【写作要点】
- 一般不必穷举,概括描述关键开放能力即可。
【写作要求】
清晰易懂,避免模糊、晦涩、有歧义的表述。
仅使用必要的术语、缩略语或专有名词,并给出解释(提供到术语表链接也可以)。
文中使用的术语、缩略语或专有名词应全文保持一致。
【写作样例】
- 音频编码:音频类应用(比如音频通话,音频录制等)可以将未压缩的音频数据送到音频编码器进行编码,应用可以设置编码要用到的编码格式,码率,采样率等参数,控制编码的输出,达到压缩音频文件的目的。
- 视频编码:视频类应用(比如视频通话,视频录制等)可以将未压缩的视频数据送到视频编码器进行编码,应用可以设置编码要用到的编码格式,码率,帧率等参数,控制编码的输出,达到压缩视频文件的目的。
亮点特征
可选。介绍Kit/方案/特性/功能/模块相对业界类似能力的亮点、优势,支撑选型。
【开发者关注点】
该Kit/方案/特性/功能/模块有哪些优势?我要不要选择它?
【写作要点】
- 提供有吸引力的亮点、优势,避免言之无物的广告语。如无明显亮点,可以不提供。
【写作要求】
清晰易懂,避免模糊、晦涩、有歧义的表述。
仅使用必要的术语、缩略语或专有名词,并给出解释(提供到术语表链接也可以)。
文中使用的术语、缩略语或专有名词应全文保持一致。
【写作样例】
- 低时延播放
提供统一音频低时延/非低时延播放能力接口,通过垂直打通硬件,达成最低的音频输出时延。在游戏、提示/告警音、K歌等场景下,可以通过低时延接口,实现音频快速流畅播放。
- 低功耗播放
针对应用播放音乐、听书类长时间音频播放场景,为确保更佳续航体验,在亮/灭屏播放时采用差异化音频缓冲区处理机制,减少CPU被唤醒的频率来降低音频播放功耗。
基本概念
可选。此处放置以下各任务场景通用的基本概念。
【开发者关注点】
要使用该Kit/方案/特性/功能/模块,有哪些独有概念是我需要了解的?
【写作要点】
仅提供开发者任务中必须的概念。
运作机制、约束限制、开发过程等多个章节相关的概念在此介绍,仅某个章节用到的概念在对应章节中介绍。
业界通用的概念不用在此赘述。 注意使用业界通用术语来表达,不用华为研发内部语言。
概念之间如有逻辑关系,推荐使用图形描述。
【写作要求】
清晰易懂,避免模糊、晦涩、有歧义的表述。
仅使用必要的术语、缩略语或专有名词,并给出解释(提供到术语表链接也可以)。
文中使用的术语、缩略语或专有名词应全文保持一致。
【写作样例】
在进行关系型数据库开发前,开发者应了解以下基本概念:
- 关系型数据库
基于关系模型来管理数据的数据库,以行和列的形式存储数据。
- 谓词
数据库中用来代表数据实体的性质、特征或者数据实体之间关系的词项,主要用来定义数据库的操作条件。
- 结果集
指用户查询之后的结果集合,可以对数据进行访问。结果集提供了灵活的数据访问方式,可以更方便的拿到用户想要的数据。
实现原理
可选。此处放置以下各任务场景通用的实现原理。
【开发者关注点】
该Kit/方案/特性/功能/模块是如何工作的?关键步骤相关接口调用和触发时机?我要了解其原理,以更好的使用、调试它。
【写作要点】
如果原理简单,通过前面基本概念就可以说清楚,此章节可以不提供,删除即可。
仅描述开发者任务(使用或接入)过程中可见的机制原理,不要提供开发者不可见的内部实现。
尽量图文结合,一般使用时序图、流程图等形式。文字描述与图形描述匹配。
注意不要泄密。
【写作要求】
清晰易懂,避免模糊、晦涩、有歧义的表述。
仅使用必要的术语、缩略语或专有名词,并给出解释(提供到术语表链接也可以)。
文中使用的术语、缩略语或专有名词应全文保持一致。
【写作样例】
分布式数据对象生长在分布式内存数据库之上,在分布式内存数据库上进行了JS对象型的封装,能像操作本地变量一样操作分布式数据对象,数据的跨设备同步由系统自动完成。
图1 分布式数据对象运行机制
约束与限制
可选。此处放置以下各任务场景通用的约束与限制。
【开发者关注点】
我要使用该Kit/方案/特性/功能/模块,有什么约束条件吗?该Kit/方案/特性/功能/模块实现的程度如何,能满足我的需求吗?
【写作要点】
描述对开发活动有影响、可感知的约束限制,及其带来的影响,包括但不限于如下几方面:
- 功能限制
- 功能使用范围(明确不支持的场景)。
- 规格限制。
- 操作限制
- 已知问题的操作。
- 潜在风险的操作(如引起性能降低)。
- 功能限制
容易出错的操作在步骤里描述,不在此体现。
【写作样例】
设备限制:XXX(正式对外宣称的设备品类名,如2in1)设备暂不支持使用本Kit。 or 本Kit仅适用于(正式对外宣称的设备品类名,如2in1)设备。 or XXXXXX及以上版本的XXX设备才可使用本Kit。
不同设备间只有相同bundleName的应用才能直接同步。
不建议创建过多分布式数据对象,每个分布式数据对象将占用100-150KB内存。
每个分布式数据对象大小不超过500KB。
与相关Kit/方案/特性/功能/模块的关系(按实际主题写作)
可选。有些Kit/方案/特性/功能/模块涉及联合使用或相互依赖,有些存在相似/相关场景等,在此处明确相互关系。
【写作样例】
关键资产存储服务仅提供短敏感数据(不超过1KB)的安全存储能力,如业务希望对超长的数据提供保护时,请考虑使用通用密钥库系统或加解密算法库框架保护您的数据。
相关实例
可选。此处放置以下各任务场景通用的相关实例。
【开发者关注点】
有哪些Sample code、Codelabs、Demo工程可供学习、参考。
【写作要点】
已发布的Sample code、Codelabs、Demo工程包,请在此处提供链接(一般为Gitee链接)。 注意:不允许将工程包等作为附件插入到文档中。
【写作样例】
针对Ability开发,有以下相关实例可供参考:
环境准备
可选。
根据具体的开发场景分析分解情况,本节内容可按需放入“开发指导”下,作为“前提条件”或“开发准备”与具体场景的“开发步骤”就近放置。
明确如何准备开发环境(如软硬件配置要求、工具要求、设备要求等)。
如果不涉及上述特殊要求,此章节删除。
环境要求
【写作要求】
明确开发环境所需要的软硬件配置,旨在要用户提前准备环境。如果软硬件内容比较多,可以再增加子标题。
【写作样例】
Hi3861开发板对环境配置的特有要求如下表所示。
表1 Hi3861开发板对环境配置的特有要求
平台类型 | 开发工具 | 用途 | 获取途径 |
---|---|---|---|
Linux服务器 | SCons3.0.4+ | 编译构建工具 | 通过互联网获取 |
Linux服务器 | build-essential | 编译依赖的基础软件包 | 通过互联网获取 |
搭建环境
【写作要求】
描述搭建开发环境的具体步骤,如果内容比较多,可以再区分章节,如:搭建编译基础环境、搭建编译工具环境等。
【写作样例】
打开Linux编译服务器终端。
运行如下命令,安装工具安装包。
xxxxx
- 运行如下命令,查看是否安装成功。
xxxxx
检验环境是否搭建成功
【写作要求】
环境搭建完成后,需要明确给出环境搭建是否成功的检验标准,也可以与搭建步骤合一。如上述写作样例。
xxx开发概述
可选。
当Kit/方案/特性/功能/模块的任务场景、场景间关系不是显性呈现的信息,且这些信息不适合直接放入开篇“xxx 简介”时,需要提供本节,用于承载:任务场景概况(任务场景划分维度等)、场景间关系介绍(何时选择各场景)等。
如果开发场景相对简单,可以不提供本节,在“xxx 简介”中酌情简述即可。
任务场景n(使用具体任务/场景名称替代,只有1个场景时使用特性名称xxx)开发指导
必选。
【开发者关注点】
我要使用/接入这个Kit/方案/特性/功能/模块,需要怎么做(how)?
【写作要点】
贴近开发者实际开发场景:
开发者需要通过哪些任务来达成开发目标,这就是任务场景。
任务场景可以有1个或多个,可按需添加多个“开发指导”章节。同时要遵循分层分级逻辑,即大场景(任务场景n)->小场景(子任务场景n-x)->任务逻辑(对应“开发流程”)->操作步骤(一个个step)。
任务场景n概述
可选。
用于承载任务场景n直接相关的概述内容,例如任务场景介绍、开发思路、选型建议以及本级任务场景相关的概念、原理、约束限制等。概念、原理等同类知识点写作要求请参考开篇的“xxx 简介”。如无,则删除。
开发流程
【写作要点】
可选。当开发步骤较多(达到5步及以上核心操作)或步骤间存在复杂的逻辑关系时,请提供开发流程,让开发者对他要执行的操作有一个全景认知。
一般使用流程图、表。
接口说明
【写作要求】
可选。描述以下开发步骤中有哪些关键接口,并提供接口简介。旨在要开发者在开发前有大体了解,提升开发效率。
_如果相关接口超过10个,只提供主要接口即可_。
接口及其涉及的功能必须在文档发布时的对应版本已支持。
【写作样例】
通知关键接口如下表所示。具体API说明详见API参考(这里提供到相应API参考节点的链接)。
表1 通知使能开关接口功能介绍
接口名 | 描述 |
---|---|
isNotificationEnabled(bundle: BundleOption, callback: AsyncCallback<boolean>): void | 查询通知使能开关 |
enableNotification(bundle: BundleOption, enable: boolean, callback: AsyncCallback<void>): void | 设置使能开关 |
开发步骤
【写作要求】
必选。
完整性、正确性要求
- 描述开发的完整过程,使开发者能够完整(如HAP中代码、资源、第三方库及应用配置文件都涉及哪些相关步骤)、正确的完成开发,不可遗漏关键配置操作。
- 文档中的片段示例代码直接拷贝进DevEco Studio中,放入上下文可以正常编译。
- 文档中的完整示例代码直接拷贝进DevEco Studio中能够运行,并和文档中描述的执行结果一致。
清晰性要求
每个步骤有清晰的执行主体(who),明确操作目的(why)、操作内容(what/how)、场景(when/where)。使用祈使句描述步骤。
步骤中如果涉及接口调用,需要清晰给出使用的接口及其使用说明、示例代码。
关键步骤和示例代码中有开发建议或注意事项的位置,需要提供相关描述(示例代码中采用注释)。 变身开发者,假想自己在操作,可能会提出什么问题?这些问题就是开发者的障碍。需要在文档中提供支撑信息,来帮助开发者处理及应对这些障碍。例如:
分支选取原则:步骤分支选取原则、参数选取原则或建议。
必要的随操作步骤就近放置的补充说明:可能存在的特殊操作、操作权限要求、效率提升技巧、几句话即可说清的背景知识等。
需要事先告知用户并提醒注意的信息:对其他功能可能造成影响的操作;对系统性能、可靠性可能造成影响的操作;可能导致数据丢失或各类安全问题的操作。这些信息需要在“操作步骤”开始前,以区别于正文的样式加以提示强调。
防错/纠错信息:针对开发全流程中可能遇到的典型问题,提供预防、定位或恢复指导,以提高开发效率。防错/纠错信息可酌情在“开发步骤”或下文的“常见问题”中承载。
规范性要求
- 保证示例代码的逻辑/语法正确性、书写规范性。涉及用户手机号码、身份证、帐号名等敏感信息均需要打码处理,如186********;涉及IP地址、域名等,需要使用私网IP或相应格式代替,如xx.xx.xx.xx、www.example.com,禁止使用真实IP地址、域名。
- 代码显示符合代码缩进要求。缩进不要用tab键,改为4个空格,否则上网格式错乱。
【写作样例-节选】
- 导入PhotoPicker模块文件。
import {
PhotoPickerComponent,
PickerController,
…
} from '@kit.MediaLibraryKit';
import { photoAccessHelper } from '@ohos.file.PhotoPickerComponent';
- 创建Picker组件配置选项实例(PickerOptions)和控制实例(PickerController)。 通过PickerOptions,开发者可配置Picker宫格的样式(如勾选框背景色、文本颜色等)、滑动预览方向、最大选择数量等参数。 通过PickerController,应用可向Picker组件发送数据。
// 组件初始化时设置参数信息
pickerOptions: PickerOptions = new PickerOptions();
// 组件初始化完成后,可控制组件部分行为
@State pickerController: PickerController = new PickerController();
调测验证
【写作要求】
可选。开发完成后,如有独立的调测验证操作,需提供指导,以确认操作是否成功。操作步骤要求同“开发步骤”。
此处仅提供最后的业务调测,每个小任务的操作结果,推荐在开发步骤执行完成后及时验证。
常见问题
可选。
【开发者关注点】
该Kit/方案/特性/功能/模块开发全流程中可能遇到哪些典型问题?如何定位、解决?
【写作要点】
描述开发过程遇到的各类问题以及解决方案,以提高开发效率。
如果无常见问题,删除此章节。
各任务场景通用的常见问题,建议以单独章节呈现;单个任务场景相关的常见问题,放在对应任务场景的章节下即可。
1.XX问题
具体写作模板请参见《FAQ模板》。
你可能感兴趣的鸿蒙文章
- 所属分类: 后端技术
- 本文标签:
热门推荐
-
2、 - 优质文章
-
3、 gate.io
-
8、 golang
-
9、 openharmony
-
10、 Vue中input框自动聚焦