为何“直给”
什么是“直给”？如字面意，就是直接给ta，不藏着掖着。在技术写作方面，我认为“直给”是最有效的思维方式。
为什么？
- 有效传播
技术写作是技术传播的一种方式，在评价技术传播的有效性时，我们会考虑到是否可以使受众“尽快获取所需信息”。“直给”正是基于用户需求，帮助用户通过最短路径获取技术信息。事实上，帮助文档的用户要不是遇到了迫切需要解决的问题，一般基本不会闲下来通读技术手册。 - 使用导向
在技术写作中，与用户需求形同对立的是功能定位。产品团队提供的写作或产品介绍素材中，往往更多地关注功能本身，因为产品团队花很大精力设计并实现功能，自然对功能的特性有强烈的表达欲望。但用户在使用功能时，往往不关心功能如何实现，只考虑如何使用。
作为产品设计者和用户之间的桥梁，技术作者“传译”技术信息的过程，必须在功能定位和用户的使用需求间进行权衡。只照搬产品团队提供的技术素材作为输出，肯定是不够的。如果运用“直给式”思维，则可以辨别哪些信息不便于用户理解和使用，再结合一定的方法实践，可以将原始素材优化后直达用户理解的核心。 - 同理心态
说实话，“直给”不过是我拍脑门想出来的一个词儿；之所以用它，是因为“直给”确实形象地传达了技术写作过程中公开分享的同理心态。论语中记录了孔子这样一段自白：“二三子以我为隐乎？吾无隐乎尔。吾无行而不与二三子者，是丘也。”试想，技术作者新接触一项技术，通过反复琢磨思索，搞明白其中究竟后，再通过文字向用户转述，自然产生让用户别走弯路、直达根本的初衷。
如何“直给”
“直给”本质上是一种写作思维方式，表示将用户基于特定场景需要了解的信息和操作直接传达出来，无需用户进行任何猜想。实际上，我们在技术写作中关注的多种实践技巧，都与“直给”的目标不谋而合：
- 技术梳理：指技术作者在技术写作前，全面梳理要描述的技术内容，掌握技术的实现原理、应用场景、使用方式等，在技术通晓的基础上开始写作。
这点容易被忽视，尤其是已有丰富素材的场景下。但是这点很重要，因为只有先清楚认知技术后，才能用自己的语言去描述技术；否则在写作过程中，会下意识地依赖素材，无法公正地去组织信息架构和对素材做出取舍。完成技术梳理后，把原始素材放到一边再开始写作，可以轻易做到按作者思路来组织结构与语言，对素材随取所需。 - 场景化写作：在产品功能描述中，明确目标用户的使用场景，说明在具体场景下，功能帮助用户解决什么问题/需要用户做什么。
所谓场景化，是让有相关需求的用户，能够快速辨别一篇文档或某些内容是否可以满足自己的需求。这里需要技术作者首先站在使用者的立场，模拟功能的实际应用场景，感受要描述的功能在什么情形下能够做什么/如何做；然后在明确场景划分的基础上来组织语言，通过文字讲出用户在具体场景下的需求，自然而然地引出对应功能或操作。 - 用户需求视角：在技术细节描述中，时刻关注用户的需求，使文字描述与用户的操作目标紧密关联。
使用服务/功能过程中，用户更关注做什么如何做，而非是什么，因此在技术写作中，往往更推荐使用动宾词组，引导用户实现操作目标。技术写作中经常遇到要去描述参数配置，以API文档的请求参数为例，如能在参数描述中包含操作语境，会使参数说明更易理解和接受。 - 文档易用理念：在部分复杂场景下，为保证内容准确性，会引入大段比较绕的逻辑描述，影响技术信息的易理解性。这时需要技术作者跳出固有框架的限制，尝试更有效的表现形式，使复杂信息变得更易于接受。
案例剖析
以下将介绍一个运用“直给式”思维的写作案例，帮助大家通过实践，体验直给式优化的效果。
案例是阿里云增强版实人认证服务下的一篇API文档。先简单介绍一下实人认证服务。实人认证是一款基于SDK客户端集成的活体检测、人脸及身份信息比对服务。它的目标用户是App开发者，开发者将实人认证SDK集成到自己的App程序中，就可以使App具有实人认证的功能，认证App用户的真实身份。
按照认证方式不同，实人认证分为不同的场景。例如，最简单的身份证号+姓名方式，只需要App用户提供对应信息即可（例如，手游App的防沉迷实名认证）；复杂场景下，需要App用户做指定的摇头、眨眼等动作，用于验证对象是一个真人活体，再结合身份信息完成实人认证（例如，金融类App的关键操作验证）。
问题分析
案例文档介绍了一个基于银行卡号验证用户身份信息的接口。
以下截图是笔者初见这篇文档时的样子，和当前线上版本有差异。
对于没有深入了解实人认证产品的用户，该内容使用起来很困难。原文存在以下描述不清楚的问题：
- 标题不明确，使用名词词组，读了莫名其妙，不知道可以帮用户解决什么问题。
- 短描述只是标题的简单重复，没有引导作用，读了根本不知道在什么场景下应该用这个API。
- 使用说明只是从功能定位角度来介绍，功能可以这样、可以那样…，读了有一种“关我啥事”的感觉，因为没有与用户操作情境关联的任何信息，即需要用户做什么、从而实现什么效果。
- 请求参数描述也只是从功能定位角度介绍，没有与用户操作逻辑的关联解释，即设置参数有什么效果、对其他操作有什么影响等。
通读下来，整体感觉有很大猜想空间，一般用户读不懂根本不会看、有需求用户不得不看，不过得耐心琢磨，体验并不好。
技术梳理
在正式写作前，那我们就先来猜一猜这个功能的原理和场景，进行技术梳理。首先请大家模拟自己是App的终端用户。以手游App为例。我们在手机上安装手游App并登录，首次进入游戏时，一般会收到弹窗提示“需要实名认证”。这时，我们只有填写了正确且相互匹配的身份证号+真实姓名，才能完成认证并继续游戏。假如我们抱着侥幸心理，随便编写一个姓名和身份证号并提交，则会收到认证不通过的提示。
那么问题来了，
Q：手游背后的游戏开发商如何做认证？手游怎么知道我们（即App用户）填写的信息是对的？
A：需要通过公安系统来核验。
Q：手游如何使用公安系统的服务？
A：通过实人认证提供的API接口。只要手游App把收集到的用户信息通过API请求参数提交到实人认证服务端，实人认证就会直接返回认证结果（背后是阿里云实人认证对接公安系统的服务进行核验）。
理解这层逻辑后，我们假想这样一个场景：假设某个手游App限制只有持有银行卡的用户才可以使用。
那么就要App用户提供有效的银行卡号（可以直接输入卡号或者对银行卡拍照并上传图片）和用户真实姓名等信息，然后进行银行卡号与用户信息的匹配认证。手游自己不做认证，来找我们实人认证服务。这个场景不就是以上案例文档要说明的API嘛~
功能描述优化
对象 |
After |
Before |
直给式写作思维运用 |
标题 |
基于银行卡号的用户身份信息核验 |
银行卡要素核验 |
优化后的标题精确地定位了用户需求，即做身份信息核验，银行卡号只是一种途径。类似的，其他API标题也可以使用该句式（基于xx的用户身份信息核验），因为实人认证服务本身的目标是帮助App开发者做App用户身份的核验，使用该句式让读者一目了然 |
短描述 |
本接口帮助您通过光学字符识别技术OCR（Optical Character Recognition）识别银行卡号，并可核验银行卡号与指定的用户信息（例如，姓名、身份证号、手机号）是否匹配。如果您的业务需要终端用户提供银行卡信息以完成身份认证，推荐您调用VerifyBankElement接口。 |
调用VerifyBankElement接口发起银行卡OCR或二三四要素认证请求。 |
使用“帮助您xx”句式，从解决什么问题角度入手，其次通过“如果您需要xx”句式讲出来用户有什么需求时，可以用这个接口。这样用户读了标题和短描述就立马清楚要不要接着看下去，没有任何疑虑。 优化前过于强调“二三四要素”，这可能是产品功能的亮点，但对用户是否应选择该功能没有帮助，而且这个信息属于功能细节，在有限篇幅内没有解释清楚，只是抛出来概念，会让读者一头雾水，不如使用用户便于理解的“用户信息”更合适。 |
使用说明 |
根据您需要的认证强度不同，本方案分为以下场景：
在二、三、四要素认证中，您可以使用OCR识别的银行卡号（需通过请求参数传入银行卡照片），也可以使用您设置的银行卡号（需通过请求参数传入银行卡号）。 |
进行银行卡照片OCR、银行卡二要素（银行卡号+姓名）、银行卡三要素（银行卡号+姓名+身份证号）、银行卡四要素（银行卡号+姓名+身份证号+手机号）等认证。 |
优化前在介绍二三四要素认证时，采用纯功能定位的视角，未解释功能与用户操作目标的关联关系；优化后先明确场景划分依据（用户可以自主选择的强度），使用完整句子（核验xx是否匹配）说明多要素认证的本质是比对身份信息是否匹配，不需用户猜想，并补充了原文遗漏的可直接传银行卡号进行认证的场景描述。 |
参数描述优化
接下来是参数描述的优化。
通过使用说明，我们得知本接口实际包含7种使用场景（对应流程图中的结束节点）。在每种使用场景下，用户需要传入的API参数有所不同（对应流程图中的绿色过程框）。
API请求参数按照技术逻辑分为3类：
- 选择使用场景：Mode参数。
- 选择银行号获取方式：
- OCR：通过BankCardUrl传入图片的公网访问地址、通过BankCardFileObject传入图片的本地访问地址。两种方式二选一。
- 手填：通过BankCardNo传入银行卡号。
- 选择几要素认证（用户信息型参数）：
- 二要素：只传入IdName。
- 三要素：传入IdName+IdNo。
- 四要素：传入IdName+IdNo+Mobile。
以下截图是笔者初见这篇文档时的样子，和当前线上版本有差异。
如何将这些参数信息准确、有效地传递给读者，是本文面临的挑战。
接下来看下如何在明确场景划分的基础上，运用直给式思维来优化参数描述。终极技巧就是在参数描述中随时关联场景信息及用户操作目标。
直给式的描述优化建议如下：
类型 |
After |
Before |
直给式写作思维运用 |
Mode参数取值 |
|
|
优化前是完全的功能视角（选择模式即选择功能，例如识别、认证功能），没有和用户操作的关联信息，需要用户纠结一下选了究竟是啥效果。 优化后则明确说明该模式需要用户做什么、能够实现什么，使用户无需揣度。 |
银行卡号获取型参数 |
|
|
在请求参数描述中，使用动宾结构语句，引导用户操作（设置xx），并在动宾语句中增加操作目标信息（要核验的xx）与用户边看文档边操作情景下的心理接受预期更吻合，相比于优化前只是直白地解释这个参数是什么，更能激发用户去完成操作。 在参数补充说明中，除了介绍客观依据（Mode取值为xx），也补充关联的场景信息，因为用户在操作过程中对自己的需求及操作目标更清楚，而非参数设置，让用户看到无需回头查看其他参数的描述。 此外，原文在介绍银行卡照片获取方式时，遗漏了场景前提。只要做了清晰的技术梳理，就可轻易发现该问题，并纠正它。 |
用户信息型参数 |
|
|
该部分参数优化的思路与上一页类似。有一处区别，优化后在参数描述中进一步补充了参数设置的影响，使用户知其所致。 |
阅读体验优化
未优化前的内容看了不能用于指导操作，但是，即使完全按照以上建议优化了内容，还是存在不好用的问题。因为参数的相互关联逻辑较复杂，用户看起来有种眼花缭乱的感觉。这时，可以尝试“直给式”的内容结构设计。
因为场景特殊，需要跳出传统的思维框架，在合适的位置（例如，请求参数表格中间，见下图示例，或者Mode参数描述中、请求参数表前后等）提供与用户场景直接关联的参数设置建议，便于用户在与场景关联的情况下，直接理解产品设计背后的逻辑。
场景划分是金字塔尖，具体参数是塔底，从尖到底去阐述更清楚、易理解。
在上图案例中，如果能够结合交互式文档设计方法（例如，配置下图所示的场景页签，分场景介绍用户需要传入的可选参数），将能够为用户提供更佳的阅读体验。
以上，就是本次技术写作案例分享的全部内容，希望对你有所帮助，也希望可以听到你的宝贵建议~
