android技术文档怎么写,技术文档编写指南

技术文档编写指南

首先请阅读文案风格指南

##学习产品使用方式

最重要的必备的条件就是：

一定要亲自使用这个产品，至少是一遍通顺的流程要走完，不要求每一个接口都一定使用过，但是一个完整的功能片段是使用过，客户端和服务端的交互流程一定要清楚。

明确需求

要与文档需求的提出人沟通，确认需求，例如研发人员提出的那几个是重点功能，它涉及到的关联产品是什么，是运行在什么平台上的，用什么语言进行开发，这类重要信息要有一个汇总。

给出一个需求调研示例：

是否有写好可供参考的大纲？

解决的市场痛点是什么？

哪些功能是主要卖点和特色功能？

与主站其他产品是否有关联？

是新产品还是辅助性新功能？

开发者在什么时候引入这个产品？

该产品用什么语言开发的？

开发者使用什么语言接入？

开发者会用到的开发工具或者 IDE 有哪些？

分析产品受众

分析产品受众的含义就是，你需要明确的知道，该产品面向的开发者是那一类技术岗位的开发者，例如 Vue 的文档就是一个不错的案例，它很明确自己的受众就是想学习前端，又不知道从何学起的前端入门者，并且 Vue 也有对应高阶开发者的更深层次的文档。

所以在分析产品受众的时候可以适当的咨询该产品的产品经理和实际项目的研发人员，要对受众的资质，能力，岗位工种做一个有限范围的评估。这样为之后起草文案的大纲有一个很好的依据。

编写章节大纲

一定要明确是否要对入门级的开发人员友好

很多技术文档例如高阶 API 自查表，或者说是进阶的自带业务逻辑的案例分析，就不太适合在开篇还在继续讲解产品的定义，产品的入门用法之类的说辞。

举一个例子，数据存储开发指南 · Android 就是一篇需要对开发者友好的开头，因为这是 SDK API 功能的核心文档，它在没有被拆分出 入门篇/进阶篇/高阶篇之前，开头一定要用开发者熟悉的旧知识来解释新知识。

产品的安装和初始化教程一定要搭配最常用的开发工具的图例和脚本

例如安装 Java SDK 的时候要用到 Gradle，而安装 iOS SDK 的是有一定会用到 XCode 这一类必备的步骤和工具时，可以适当的搭配测试过程中的截图和脚本。

介绍第一个功能的时候，设计好一个使用场景

例如介绍即时通讯的时，可以从一个熟悉的微信聊天的场景抽象出来私聊，群聊，或者 QQ 的讨论组之类的，从已有的产品使用场景去抽象出一个常见的案例开始，逐步从浅到深介绍产品的第一个接口或者说功能。

参考其他友商竞品的文案不是错

产品就一定有竞品，主动去借鉴竞品所涉及到的场景，背景故事，接口描述不是错，不过切忌别抄袭的太明显，可以通过文字转换来擦去痕迹。

梳理章节标题和主次关系

主要功能和接口，还有需要依赖的工具，脚本，IDE 都要尽可能的提前登场，开发者如果准备好了，只要工具都有，他会考虑按照文档里面的步骤一步一步走下去的。

切忌把接口直接罗列在标题上

一个错误的案例就是 jQuery 的方法列表， jQuery 的文档属于高阶开发者的速查表，不属于一个技术文案的范畴。

用开发者一眼就能明确含义的文字做标题最好

一些的正确的范例：

用户登录

创建 AVIMClient

向对话发送消息

申请邮箱验证

减少冗余描述

牵涉到关联产品的时候，贴上对应产品的链接

不用做过多描述，只要陈述有依赖，有前提，不熟悉的新手用户自然会点击，同时也不会干扰已经熟悉的用户的阅读体验。

时序图的运用

时序图已经在文档项目中直接支持用 md 标记生成，在针对步骤超过 3 步的接口调用的时候，搭配时序图会更好。

示例代码的优化

这个难度较高，建议有编码经验的文档编写者，从现有的示例代码中参考。

全文第一段示例代码尽可能做到如下几点：

有初始化模块的代码

有登录/打开/创建等关键性代码

第一个功能接口搭配详细的代码注释

代码结尾给出当前代码如果就此结束，对象的客户端状态以及服务端状态