客户端SDK接入文档，这么写就对了 | 技术写作

最新推荐文章于 2023-10-08 16:15:11 发布

睿齐

最新推荐文章于 2023-10-08 16:15:11 发布

阅读量3.3k

点赞数 2

文章标签： java android 编程语言 linux 大数据

本文链接：https://blog.csdn.net/BGRichi/article/details/108675652

版权

开发文档通常包括哪些类型？命令说明、错误信息说明、告警说明、事件说明、关键技术指标说明……但是，在云服务的世界里，个人以为，最常用到的2类开发文档是，API接口说明（下文简称“API文档”）和SDK接入说明（下文简称“SDK文档”）。

作为产品的重要组成部分之一，文档的质量一定程度上反映了产品的质量。如果文档质量无法满足用户需求，可能会劝退试用产品的潜在用户。同时，如果用户无法通过文档独立使用产品，只能求助于技术支持，带来较高的运维成本。

而且，在云服务世界里，用户以开发者为主，因此开发文档的重要性，往往超过操作界面的使用说明。

为了提升开发文档的质量，TC研修实验室曾介绍过API文档的写作方法，参见：开源世界，更加需要过硬的接口文档 | 技术传播。那么，今天我们就再来聊聊，相对复杂一些的，客户端SDK接入文档吧。

本文主要包括以下内容：

内容设计。介绍SDK接入文档与周边类型文档的关系，以及内容拆分原理。
内容架构。介绍SDK接入文档的一般内容架构，即写作模板。
写作要点。介绍SDK接入文档写作过程中的常见问题，及写作技巧。

全文：2800字

说明：王老师对此文亦有贡献。

内容设计

由于SDK文档具有篇幅较长的特点，因此在设计或优化SDK文档时，需要对内容架构进行充分考虑，可以从以下几个方面入手：

基于操作步骤进行拆分

按照操作步骤进行拆分是最容易想到的方法，简单粗暴。不过为了避免内容过于碎片、凌乱，要考虑步骤与步骤之间的关联性，将强相关的步骤进行必要分组。

基于使用场景进行拆分

如果不同用户群接入云服务的方式存在差异，可针对不同使用场景，对SDK文档进行拆分。例如，区分iOS/Android终端；区分手机厂商；区分手动/自动添加依赖等。

基于内容类型进行拆分

与SDK接入操作弱相关的内容，可依据其内容类型，拆分到其他文档中体现，并添加链接进行关联。

SDK文档与其他类型文档的关系如下图所示。

文档类型	说明
API文档	当SDK文档中涉及API调用，可索引至相关API文档。
术语解释	当SDK文档中存在较难理解的术语需要详细说明，可索引至术语解释或者相关说明页面。
用户指南	当SDK文档的前提条件中涉及已完成的操作和配置，可索引到用户指南或单独的操作页面。
常见问题	常见问题作为用户经常出错的地方，需要在文档中补充相应警示信息，并索引到相关解决办法。

内容架构

一篇完整的SDK文档的基本内容架构如下所示。

一级目录	二级目录
前提条件
使用限制
接入说明
操作步骤
	步骤1：准备
	步骤2：添加依赖
	步骤3：初始化SDK
	步骤4：<初始配置1～n>
	步骤5：编译设置
	步骤6：调试
初始值说明
接入验证

前提条件

说明执行当前操作需要满足的条件，包括但不限于：权限、已完成的操作/配置。同时，考虑到前提条件不满足的场景，需添加索引，指导用户进行相关操作。

例如：

已具有某产品使用权限。具体操作参见：申请使用权限
已获取某产品配置信息。具体操作参见：获取产品配置信息
已创建实例。具体操作参见：创建实例

使用限制

说明当前操作无法支持/适用的场景，包括但不限于：系统、环境等。如产品/服务无法支持/适用用户期望的场景，须提前告知，避免徒劳。

例如：

仅支持Android 4.2及以上版本。
仅支持4G及以上通信网络。
仅支持Framwork 4.0及以上版本。下载：Framwork最新版

示例代码

样例代码中的信息需要与文档中的信息保持一致。包括但不限于：SDK包及其依赖文件的版本号；添加代码段的位置说明等。

接入说明

如操作步骤较长，细节繁密，可进行概述说明，帮助用户理解完整的操作逻辑；同时，按步骤提前警示用户可能出现的错误，例如，依赖冲突。

接入说明与操作步骤是“总-分”的关系，步骤需一一对应。

例如：

准备。下载配置文件，获取公钥。
添加依赖。可采用自动/手动2种方式添加依赖；处理倚赖冲突。
接入服务。添加SDK初始化代码。
编译设置。注意：如设置错误，可能导致编译失败。

操作步骤

操作步骤可具体细分为准备、添加依赖、初始化SDK、<初始配置1～n>、编译设置、调试等。

步骤1：准备

后续操作依赖的前期准备工作，包括但不限于：下载软件包；获取配置信息等。与增加单独的操作页面，并在前提条件中索引，效果相同。

步骤2：添加依赖

如存在多种添加依赖的方式，需分别说明。例如，手动接入；自动接入等。

如存在依赖冲突场景，需说明处理办法。例如：如已添加某产品的依赖，可能出现依赖冲突，具体解决办法参见：依赖冲突解决办法

步骤3：初始化SDK

提供样例代码段，及配置说明。

步骤4：<初始配置1～n>

如存在初始配置项，需逐一进行说明。每步骤实现一个配置。例如，混淆配置；安全配置等。

步骤5：编译设置

如对编译设置有要求，需进行说明。

步骤6：调试

如调试阶段对排查错误有可借鉴的经验，可进行说明。

初始值说明

如系统提供默认的初始值，可进行说明。

接入验证

验证业务是否成功接入。需充分考虑：

端侧/服务侧业务流程；
端侧/服务侧可能出现的错误；
充分考虑端侧/服务侧的错误排查方法；

形成一系列操作/判断，帮助用户定位/解决问题。

写作要点

补充说明/注意

基于已有用户反馈/问题，在相应位置补充必要说明/警示，帮助用户避免此类问题。

明确操作目的

操作说明需明确操作动作，以及操作目的。

错误：添加以下代码段。

正确：添加代码段，定义Application类，编写OnCreate方法启动服务。

区分指定/设置

配置项说明需区分指定和设置。

1）指定：配置项/参数为既有信息，需说明如何获取。

2）设置：配置项/参数为初次设置，需说明如何配置。

配置说明需充分考虑接口定义，并尽可能包含以下信息：

数据类型	区分数值型/字符型/枚举型/对象/JSON
取值范围	字符串长度限制；数组大小限制；数值大小限制等。
是否必选
能否为空
默认取值	如数据类型为枚举型，是否一般设置默认取值？
字符类型	如数据类型为字符串，需说明是否支持英文大小写、中文、数字、特殊字符等。
唯一标识	配置项/参数是否为键值。
大小写敏感	如配置项/参数是唯一标识，是否大小写敏感。
格式要求	如字符串需满足指定格式，需说明。
其他	如配置项/参数倚赖其他配置项/参数；或者配置项/参数对其他配置项/参数有影响，需说明。