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)?
-
遵循分层分级逻辑:场景(任务场景)->任务逻辑(开发流程)->操作步骤(step by step)。
-
当开发步骤较多,请提供流程图。
操作步骤
【写作要求】
【写作要求】
必选。
-
每个步骤有清晰的执行主体(who),明确操作目的(why)、操作内容(what/how)、场景(when/where)。使用祈使句描述步骤。
-
保证示例代码可执行。
-
开发完成后,需提供指导以确认操作是否成功。
-
涉及用户手机号码、身份证号、账号名等敏感信息均需要进行脱敏处理,例如:186********;涉及IP地址、域名等信息,需要使用私网IP或通用示例格式代替,例如:xx.xx.xx.xx、www.example.com,禁止使用真实的IP地址或域名。
常见问题
可选。
【开发者关注点】
开发流程中可能遇到的问题。
【写作要点】
描述开发过程遇到的各类问题以及解决方案,以提高开发效率。
具体写作模板请参见《FAQ模板》。
后续操作
【写作要点】
使用无序列表(不超过 5 项),列举开发者可能接下来有兴趣的主题。