不整虚的，今天来点干货，po主搞过项目后的总结，大家相互学习，多多建议。
一、什么是产品接入文档？
接入文档是为了帮助使用你产品的开发者们提供便捷的接入渠道指导，帮助了开发者快速完成对应产品模块的集成上线的一份指南。
二、为什么要写接入文档？
文档的目的有两个：一是对外，让使用者接入你的产品/功能的时候不至于不知道从何开始，在开发者不清楚如何接入的时候有一个统一的文件进行沟通交流开发。二是对内，提供一套规范的接口撰写方式，方便后期人员查看、维护；同时还能让研发同学们养成写文档的习惯，做一个靠谱的人。
那么什么样的产品是需要一份接入文档的呢？需要文档的产品都有一种特质，那便是该产品会对外提供某一种能力，常以代码的形式提供。
常见于需要集成的sdk产品，提供很多api接口的产品，提供部分能力的产品或者开源产品，如：百度所提供图文转换、微信提供支付接口、支付宝提供的能力。这些功能都是需要研发同学一步一步的按照对方的接入文档要求接入，才能成功使用。
三、接入文档需要具备的特质？
文档结构清晰
清晰的文档结构，可以让使用者快速找到自己需要找到的东西。定位准确问题位置或者保障自己的目的快速实现。对于b端的产品来说“效率至上”
接入流程简洁
接入步骤尽量经过严格设计，在用户不了解你的产品情况下，你的步骤长且不清晰越会让他他觉得接入是一座无法跨越的大山；而如果你将步骤拆解成为几个阶段目标，那么接入者拥有可掌握的目标，便成为翻越小山。
例如一款支付sdk接入，可以按照真实用户使用流程步骤设计：【资源导入/集成】—【初始化】—【打开支付页面】—【选择支付方式】—【支付成功】
此处注意几点：
1、接入流程中尽量只包含【必接项目】，若包含【非必接】一定标注出来
2、接入步骤可按照场景拆分、使用流程拆分
功能模块健全
一份合格的接入文档一定是需要将产品的所有功能进行涵盖的，功能按照模块拆分，按照清单记录可便于客户了解你的产品/报价，或者是提供接入者快速定位功能板块
接入自测简单
接入完成后，开发者需要验证SDK接入是否成功。那么我们最基础的方法是，提供给开发者接入清单，自查功能接入是否完成；提供开发者教程，查看日志或者观测某一现象判定自己是否接入正确。
当然如果可以，你甚至可以开发一个帮助开发者检测接入是否完成的工具。
语言小白易懂
写文档时，需要记住的一点，把你的阅读者当小白。他是新客户没有你那么了解产品，也没有你的研发熟悉代码，你们常说的俗语对他来说可能是天书。甚至你都不知道接入者到底是技术大佬还是实习生。（小声逼逼，甚多公司专找实习生搞接入）他们真没你想的那么厉害，语言简洁清楚写！！
问题覆盖全面
一份接入文档，还需要具备的是如果接入者遇到问题怎么办？那么我们需要列举出常见技术问题以供解决，比如如何解决冲突啦，导入不成功啦等等，详细的常见问题或许能减少你们公司对客户的技术支撑，让研发们多点时间搞代码。
ps：参考时不要只看微信、阿里的文档了，他们写的健全但是看起来真的费研发，看看这些还不错的站吧～
https://docs.doppler.com/docs/enclave-guide
https://docs.developer.yelp.com/docs/api-testing-guidelines
四、文档结构设计
开头不得不说一句，技术文档多是用markdown写，咱们产品同学要帮助研发检查的话，还得学习一门新技术，当然也不难。
分享一下我经手项目的文档结构，仅供参考，相互交流：
## 产品介绍
由产品经理负责主要编写，集中说清楚以下事项：
该产品有什么作用 (WHAT)
该产品的目标对象是谁 (WHO)
该产品适用于在什么场景下 (WHERE)
其他相关信息，如支持平台或技术、产品优势、主要功能简介、兼容性等
引出如何使用该产品 (HOW)
## 使用指南
主要为用户提供相关前置准备工作，常见的如后台注册、SDK 下载、Demo 下载等。
### 平台注册
如果需要注册后台，则须清楚说明：
后台的作用
后台的访问地址，是否有限制等
需要从后台获取的参数及相关截图
### SDK 下载
提供最新版本的下载地址
提供过往版本的发布日期、版本号、版本记录以及下载地址
### Demo 下载
Demo 是为了让用户更快的体验产品，并且帮助开发人员在接入过程中能够有参考可依。这里提供一下内容：
1、Demo 客户端下载，可直接在手机或电脑端运行，查看最终效果
- 研发需保证 Demo 客户端可用，并且包含大多数基本功能
2、Demo 工程文件（源代码），方便用户快速在本地运行及参考
- 示例源码运行指引，通过一步步教程式的说明及配图，向用户说明如何在本地运行该 Demo
- 研发需保证 Demo 示例源码在引导下可以顺利启动
3、常见问题，说明运行源码过程中可能出现的问题
## 快速开始
快速开始的目的是让用户能够用最低的理解成本去接入产品的基础功能或者主流程，从而对产品产生简单、易懂、好上手的信心，继续探索其他的高级功能。
为了达到这个目的，建议在快速开始中尽量以“第一步”、“第二步”式的教程语言进行说明，以帮助用户快速开始为主要目的，不过多纠缠方法细节。
快速开始根据产品类型不同，一般会包含接入准备、开始接入流程（教程）、查看最终效果、推荐下一步更高阶功能等等方面。
## 拓展功能
在用户完成快速开始后，需要针对场景或者功能进行更深入的尝试。切记不要把所有流程全部写在一起，尽量把流程切分为不同的场景，并且保持不同场景独立。有依赖关系的场景或模块需要在文档中说明。
## API 参考
整理所有方法的具体细节，包括 API 类型、介绍、说明、参数、返回示例、错误码等
## 常见错误码
列举常见的错误码、相关说明以及潜在的解决方案
## 常见问题
分场景或模块进行常见问题的归纳以及解答
好啦好啦，终于写完了，本来想搞两版的，一想算了，一次发完，早点看电视去～