我想建条通道 - 在技术写作中运用逻辑思维

摘自《简单的逻辑学》：

• “思维”活动指由人脑对外部事物和综合材料进行加工，逐步把握事物的本质和规律，从而形成概念、建构判断、进行推理的活动。
• “逻辑”是关于思维形式（概念—判断—推理）的科学。逻辑、思维、语言密不可分。
• “逻辑思维”指借助思维形式，遵循一定的规则和规律，运用逻辑方法，建立能动地反映客观现实的理性认识的过程。

逻辑思维在日常应用广泛，在技术写作中也不例外，体现在：

• 概念思维：

  技术是不断革新的。技术写作为技术服务，旨在向用户阐述技术。阐述的过程离不开对技术概念的定义（是什么-内涵、有什么-外延）。概念定义不清晰明白，直接导致用户无法理解产品，更不会接纳它。

• 判断思维：

  除了定义概念，技术写作也面临数不胜数的判断。如判断一个产品/功能给谁用（用户场景）、有没有限制/前提/注意事项、某项配置是否合理、操作流程是否完全等等。 判断用来回答与产品使用过程有关的所有信息的对或错。判断有误或没有给出明确的判断，将导致用户在使用产品时遇到困难，只得寻求人工支持，增加产品运维成本。

• 推理思维：

  推理指基于已有判断得出新判断的过程。只有遵循合理、严谨的推理，技术/产品才会向着正确的方向演进。技术文章中要体现合理的演绎推理思维（由一般到个别），这意味着让用户基于已有功能知识，能够顺利、确定地得出新功能的相关推测，达到轻松使用新功能的目的。若非如此，则会影响用户体验，导致用户对产品失去信赖。

在技术写作中运用逻辑思维的内涵包括：概念定义清楚、判断明确准确、推理合情合理。

本文通过几个实践案例，介绍凭借“概念—判断—推理”思维，快速、深入理解新概念的思考方法。

Case1：思考“建条通道”

回到标题，我想建条通道。在动工之前，关于这条“通道”我应该思考什么？

现实类比

首要对要建的“通道”进行定义。

“通道”是一个集合概念，用来指代任何从源头到目的地的传输途径，可以是道路、隧道、网络连接等等。计划建条通道时，首先要明确这个通道的本质属性，即区分于其他通道的特征。具体来说，需要明确：

“通道”本质属性	»	»
源头	目的地	类型/用途

让我们这样来具体定义它：

建一条从公司附近的地铁站到办公楼的步行道，方便同学们出地铁后快捷抵达办公楼。

上面的概念定义中明确了通道的本质属性，回答了它是什么（内涵）的问题。

定义“通道”	»	»	»
概念	源头	目的地	类型/用途
	公司附近的地铁站	公司办公楼	步行道，供出地铁的同学使用

以上这些认识是日常生活的常识，大家稍一琢磨便很清楚。接下来让我们进一步，看一个云产品功能设计。

功能设计

让我们来建一个“北向通道”吧。对它的定义是：

用来将“边缘计算机采集的设备数据”流式传输到支持的“数据接收方”，以便进行分析和消费。

定义“北向通道”	»	»	»
概念	源头	目的地	类型
	边缘计算机	数据接收方（sink）	流式数据传输通道，供边缘计算机采集的设备数据使用
与现实通道类比	公司附近的地铁站	公司办公楼	步行道，供出地铁的同学使用

针对以上定义，以下这些提问和判断帮助我们完善对它的认识：

• 问题1：数据北向传输过程如何？

  在边缘计算机上安装北向通道后，边缘计算机采集的数据从通道流入，然后流出到接收方（sink）。

• 问题2：“北向通道”为何如此命名？

  一般来说，通道是双向的；“北向”明确了其单向性。在互联网产品设计架构图中，一般底层数据在下方，业务应用在上方，“北向”指示了数据是底层向上层的单向传输。

功能实现及文档案例

接下来，请带着以上认识来使用产品和文档，看看是否能发现一些问题。

产品控制台及文档	逻辑问题及说明	类比现实“通道”
以下是创建北向通道的界面： 以下是文档中对数据源配置参数的说明：	⌘ 概念本身与外延混淆 已知：每个“设备实例”有唯一的“节点”、“设备模板”和“驱动模板”。它们是“设备实例”的某项特征（外延属性-不唯一指定某个设备实例）。 推测：当外延属性和“设备实例”并列展示可供选择时，合理的猜测有： 外延属性用来筛选设备实例（❌） 外延属性用来指定某类设备的集合（✅） 因为有多种外延属性，在指定时需要确保有交集。这是需要提醒用户注意的事项。	思考：通道为谁而建？ 当然是工区的同学们。你可能直观地这样认为。但仔细想一想，访客是否可用呢？如果访客可用，那么同学们的概念包含访客吗？ 其实，这个问题的答案不重要，它完全取决了“我”这个建造者。我可以选择为自己而建、为小组成员而建、为上海工区的同学而建、为拥有门禁权限的同学而建，…… 但不论如何，这个通道终归是为某个“同学集合”而建。集合中的同学要么各自单独指定、要么根据所有的共同特征指定。 这个问题反映对通道“应用对象”的判断，是必须要明确的。如果我通过多种特征组合来指定，那么应确保这些特征组合是有交集的。 示例：假如张三base在上海。如果为base在北京的张三而建，那么这条通道可能无用武之地。因为张三的base在上海，“base在北京的张三”是不存在的。
以下是北向通道的详情： 以下是文档中对接收方参数的说明：	⌘ 命名构成歧义、概念过程不清楚、推理不合榫、判断错误 已知：通道负责将来自source的数据传输到sink（数据接收方）。 推理（归谬法）：假设“数据流出”统计的是从sink流出的数据，那么需要一个运行在sink上的程序来统计数据（针对不同sink，这个程序要有不同的逻辑，以及需要定义何为流出）；再者，作为通道使用者，把数据传输到目的地（sink）即可达到目的，为何还要获知数据在目的地如何消费。以上，皆可推出不合情理的结论。 实际是通道流入和流向当前sink。文案极具误导性。	思考：通道通往哪里？ 目的地不就是公司办公楼嘛。可是仔细想一想，“公司办公楼”是一个集合概念，可以是上海办公楼、北京办公楼、……；就算是上海办公楼，同学A要去甲栋、同学B要去乙栋。不难推断，我们所说的“公司办公楼”对象实际有以下特征： 类型明确、数量有限：可具体到楼栋 现实可达：与地铁站具备可连通的条件，如距离接近（500米内）、无山河险阻 允许访问：目的地是使用者有权限访达的 这个问题反映对通道“实现目标”的判断，也在一定程度上明确了“非实现目标”。 从通道视角，使用者由地铁站进入通道，前往目标楼宇。通道要实现地铁站和具体楼宇的连通。 从楼宇视角，借助通道接引了许多同学（流入目的地）。使用者进入楼宇以后，可以各就工位，也可以自由出入，这些在楼宇范围内的活动则不是通道所关心的。 通道关心的是：一人流入必有一人流出。若只有流入，而没有流出，则指示有异常。
以下是创建北向通道的界面： 以下是文档中对连通性测试参数的说明：	⌘ 概念过程不清楚、判断错误 对数据传输的过程不清楚导致描述有问题。连通测试的是边缘计算机到sink是否网络互通（设备不是产品可控制的）。

Case2：思考“用户思维”

逻辑思维思维帮助我们识别出一些问题，要解决这些问题，可能还需借助下“用户思维”。

什么是用户思维

用户思维的本质：想用户所想。

那么，“用户”指什么？ 不管指向谁，我们说的“用户”终归是个“人”（属概念），而且可以猜想出这个“人”具有的一些具体特征，如xx从业者、有xx样的需求、……

当然，也可以想想这个用户的通用特征。以自己作为类比，

• 每天面临很多来自工作、生活的繁琐事务，喜欢接触到的事物越简单（simple）越好
• 能通过自己摆弄知道答案就绝不去查询，能看简单的示意图获得信息就绝不看文字，总之越直觉感知的（intuitive）越好

通过类似推理，不妨大胆地猜测：

你或者我们面对的用户也具有这样的特征吧：

• ✅ 喜欢凭借直觉感知新事物，追求简单、不费力、符合常识情理
• ❌ 不喜欢阅读文档、查询新概念、猜测可能出现的结果

用户想看到什么

作为这样一个用户，“我”会希望“北向通道”是什么样子呢？

• 期望1：陌生概念让我“秒懂”

  • 看到的
  • 想看到的

• 期望2：配置信息意图直观

  • 看到的

  • 想看到的

    ※ 配置数据源的的本质是选择设备实例，可以借用筛选组件的模式

• 期望3：参数文案指代清楚

  • 看到的

  • 想看到的

    ※ 文案定义清楚，不留遐想余地 |

在这个案例中，当产品满足用户希望的样子，文档对用户来说可能就变成不再需要了，这样最符合用户的期望：在第一时间清晰掌握所需的关键信息，不留悬念。

不被需要的文档≠TW不被需要

你可能会纳闷，文档不被需要，那还要TW做什么呢？请注意前提，“针对这个案例”我们能找到更有效的交互和文案设计，帮助用户理解和使用产品。而在其他案例中，文档可能是承载信息的关键。

好的文档和产品有机渗透在一起。TW关注的是用户需要了解的信息，将这些信息按照其特征恰到好处地呈现给用户，或借助交互、或借助文案、或以文档，使用这些方式的过程即信息架构。凡于用户有用的产品信息，皆TW力所能及、力所当及。

TW管理和架构对用户有用的产品信息，可以说是向用户理解负责，不当仅局限在文档页面。

Case3：思考“数据采集”

在介绍“北向通道”时使用了“采集的设备数据”这样一个概念。作为一个思维训练，我们可以来看看究竟什么是“数据采集”。

要清楚地解释这个概念，不妨这样思考：

想想你怎样采摘草莓

什么是“采集”？ 我们可以将去草莓园采摘葡萄视为“采集”、将感染新冠时对自己的体温监测视为“采集”，……

不论何种采集，它是一种行为，由发起者向目标对象实施，借助某种形式，以获取对象的全部或部分（本体或能反映本体的属性）为结果。

定义“采集”	发起者	目标对象	行为结果
摘草莓	我	草莓园	草莓入篮（借助动手摘的形式）
测体温	我	我的身体	体温被记录（借助用体温计量的形式）

定义“数据采集”

由边缘计算机（发起者）从设备（目标对象）上获取能反映设备某项属性数据的重复过程。

定义“数据采集”	»	»	»
概念	发起者	目标对象	行为结果
	边缘计算机	与边缘计算机建立连接的物联网设备	设备的属性数据被记录
说明	设备是物联网设备，与边缘计算机相互连通。 连通意味着有着共同的语言和交流模式（借助边缘计算机上运行的“设备驱动”实现）。 就像你可能会在每晚固定时间和远在异地的恋人煲电话，边缘计算机（上的设备驱动）定期向设备发起询问，如“告诉我你当前的状态”，并记录得到的答复作为数据点。		数据是“数据采集”这个行为的结果，具有以下本质特征： 由边缘计算机采集（或产生于边缘计算机） 用来反映设备属性

示例： 假设你的办公桌上放有一个环境监测装置，包含一个温度传感器和一个湿度传感器；温度传感器和湿度传感器运行时实时感知当前室内温度和湿度。环境监测装置就是一个设备。

在将设备接入到边缘计算机时，可以预设边缘计算机的数据采集行为，例如，每5秒采集（询问）一次当前温度，每10秒采集（询问）一次当前湿度，并存储获得的响应。每一个温度值、每一个湿度值都表示一个“数据点”。每一次“采集”获得的数据点数量不一定相同。

一个思维测试

想清楚了数据采集的概念，我们来做个测试~

题目
假设你有一个边缘计算机，准备用它接入一个虚拟设备（可以自动生成随机数据）。现在你要通过几个参数来指定边缘计算机对设备数据的采集行为。试看以下“变化上报”参数的描述，看看是否有什么逻辑问题。
参考答案
原文参数描述有以下错误： 行为发起者错误 采集行为的发起者是边缘计算机，描述中却暗示是设备。（设备可以是任意第三方，我们无法管控其行为） 行为结果错误。 采集的结果是边缘计算机获得数据存储在本地，上报到边缘智能控制台是“通道”作用下引起的结果。 这个参数实际指边缘计算机只在数据值发生变化时，才会执行采集（存储数据到本地），否则（即在采集时发现数据值没有发生变化）则放弃采集。

启示

回顾一下上面的思维之旅，

• 遇到新概念，先找属概念；发现其本质，思考子对象

• 定义新概念，明确清楚简；用词需统一，歧义慎避免

• 判断当准确，推理乃依据；一般到个别，演绎尤可靠

• 万物互所通，类比亦可采；待到理解透，想用户所想

简单点：

当自己以为认识足够时，不妨再多问几个问题！多想想，总会有新的认识。