跳到主要内容

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. 安装基础包，运行如下命令。

    xxxxx

  3. 查看安装版本，运行如下命令。

    xxxxx

开发流程​

【写作要点】

可选。

  • 开发者要使用这个功能/模块，需要怎么做（how）？

  • 遵循分层分级逻辑：场景（任务场景）->任务逻辑（开发流程）->操作步骤（step by step）。

  • 当开发步骤较多，请提供流程图。

接口说明​

【写作要求】

可选。

  • 描述以下开发步骤中有涉及哪些关键接口，可以链接的方式提供。

开发步骤​

【写作要求】

必选。

  • 每个步骤有清晰的执行主体（who），明确操作目的（why）、操作内容（what/how）、场景（when/where）。使用祈使句描述步骤。

  • 保证示例代码可执行。

  • 开发完成后，需提供指导以确认操作是否成功。

  • 涉及用户手机号码、身份证号、账号名等敏感信息均需要进行脱敏处理，例如：186********；涉及IP地址、域名等信息，需要使用私网IP或通用示例格式代替，例如：xx.xx.xx.xx、www.example.com，禁止使用真实的IP地址或域名。

如何自测​

可选。

【写作要点】

  1. 测试环境准备。
  2. 测试步骤。
  3. 预期结果。
  4. （可选）常见问题及解决方法。

相关实例​

可选。

场景通用的其他相关实例。

【开发者关注点】

有哪些 Sample code、Demo 可以进一步学习。

【写作要点】

已发布的 Sample code、Demo ，请在此处提供链接。

调试诊断工具​

可选。

【写作要点】

  • 调试诊断工具用于帮助开发者在开发、测试和运行过程中快速定位问题并解决问题。
  • 建议以超链接的方式提供。

常见问题​

可选。

【开发者关注点】

开发流程中可能遇到的问题。

【写作要点】

描述开发过程遇到的各类问题以及解决方案，以提高开发效率。

具体写作模板请参见《FAQ模板》。

后续操作​

【写作要点】

使用无序列表（不超过 5 项），列举开发者可能接下来有兴趣的主题。