跳到主要内容

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 项),列举开发者可能接下来有兴趣的主题。