什么是技术写作？ 定义和例子

将优秀的技术写作视为理所当然是很容易的。 如果做得好，技术交流会使复杂的工具看起来易于使用和维护。 但这种抛光的饰面是高水平技能和辛勤工作的结果。

什么是技术写作？ 请继续阅读定义和示例。

技术作家做什么？

技术写作，也称为技术交流，清晰易懂地传达有关技术的信息。 一些技术写作服务于专门的受众并使用高级行业术语。 一些文件通过简化复杂信息来面向普通读者。

这种写作对于从软件开发到制造的许多行业来说都是至关重要的交流工具。 它存在于公司运营的各个方面，从业务计划到项目管理。

技术写作的类型

科技公司和产品制造商创建了多种类型的文档。 一些，如用户手册和快速入门指南，为公众所熟悉。 其他类型的技术写作，例如案例研究和白皮书，看起来根本不是技术性的——这就是它们的价值所在。

您将在下面找到对最常见内容类别的介绍，以及帮助您描绘它们的技术写作示例。

产品文档

也称为技术文档，产品文档是大多数人在想象技术写作时所描绘的。 它解释了产品的工作原理和/或如何使用它——技术作家的两个非常不同的目标。

产品手册

产品手册，有时称为用户或用户手册，是对技术产品的全面概述。 如果写得好，它是用户日常使用产品所需的唯一文档。

如果您是车主，您的手套箱中可能有一个产品手册示例。 汽车用户手册描述了驾驶员需要访问的每个组件，从轮胎到车载诊断 (OBD) 信号系统。 它们还包括家庭维护说明，例如检查轮胎压力：

1. 拆下轮胎气门嘴盖。
   2. 将轮胎压力表的尖端按到轮胎气门嘴上。
   3. 使用压力表刻度读取压力。
   4. 如果轮胎充气压力不在推荐水平，请调整压力。 如果添加的空气过多，请按阀门中心放气。
   5. 完成轮胎充气压力测量和调整后，在气门上涂抹肥皂水，检查是否有泄漏。
   6. 重新盖上轮胎气门嘴盖。1

汽车手册是为消费者设计的。 因此，他们使用日常语言和非技术图表。 为工业用户设计的产品手册看起来会非常不同。

虽然消费者手册应该没有行话，但工业手册可以使用专业人士会理解的术语：

如果工艺需要，将排气管线连接到具有足够吞吐量的减排系统。 如果减排系统太小，DRYVAC 泵将因超压而关闭。2

这种工业真空泵的用户会理解这些术语。 不需要定义。

用户指南

人们经常争论手册和指南之间的区别，即使在技术通信行业也是如此。 普遍的共识是，指南是一个更广泛的术语，包括任何类型的针对用户的教学文档。

最重要的是，用户指南不必是冗长而详细的技术文档。 它可以是针对特定功能的教学视频，也可以是解释新手表按钮的插页。

一个示例是快速入门指南，您可以在大多数消费电子产品的零售包装中找到该指南。 今天，许多快速入门指南都带有大量插图，并且仅在必要时包含文本。 其他包括基本说明和插图，如忍者咖啡吧指南：

• 逆时针旋转储水器并取下以便于注水。
• 将新鲜的过滤水装满至水瓶外标上的玻璃瓶线。 Auto-iQ 知道根据您选择的大小和冲泡方式从中抽取适量的水。 在冲泡之前，请始终确保水箱的水量高于所需尺寸的最小填充线。
• 顺时针转动水箱以锁定到位。 3

请注意，该指南没有说明如何修理水箱或如果您的咖啡机不工作该怎么办。 为此，您需要完整的产品手册。

API 文档

在当今的超连接世界中，应用程序编程接口 (API) 文档无处不在。

API 是一组函数和指令，允许一个程序与另一个程序通信。 您最喜欢的在线商店中的“使用 PayPal 付款”选项背后有一个 API。 它支持“使用 Facebook 登录”功能，简化了各种应用程序的登录。

为了使 API 正常工作，开发人员必须将这些交互作用到他们的代码中。 API 文档引导开发人员完成该过程。 它还提供故障排除技巧、用户体验设计信息和解决用户问题的说明。

因为它是为开发人员和编码人员设计的，所以 API 文档技术含量很高。 API 编写者应具有软件或编码方面的背景。

过程文档

流程文档是一组详细的分步说明，用于执行任务。 它不同于产品文档，后者涵盖了如何使用或修复技术项目。 相反，过程文档描述了工作程序。 这里有一些例子。

标准操作程序文件

标准操作程序 (SOP) 文件定义了组织对特定过程的期望。 它们也可以称为标准工作说明、业务标准或政策文件。

SOP 文件有多种形式，包括：

• 操作清单
• 图解说明
• 流程图
• 脚本视频

流程越技术化，SOP 文件就越详细。 考虑这份描述大学机械车间车床安全程序的文档：

启动车床前，确保主轴工作已嵌入杯心[原文如此]； 尾部、尾托和刀架被牢固地夹紧； 并且旋转库存有适当的间隙。 4

像这样的文件需要对程序有深入的了解。 作者可以从直接的行业经验、与主题专家的互动或产品的实际操作中获得这些知识。

业务流程大纲

这种类型的过程文档可能技术性较低，但可能需要技术知识，具体取决于所涉及的内容。

例如，软件初创公司可能会创建流程文档来组织开发流程。 该文件将列出从计划到发布的每个阶段会发生什么。

测试计划是软件开发人员常见的一种过程文档类型。 他们为测试软件创建了一个逐步计划，包括谁负责哪个步骤以及需要什么设备。

因为这些是内部文档，所以它们往往是高度技术性的，如以下课程注册原型示例：

组装架构原型的目的是测试所选架构的可行性 [原文如此] 和性能。 在这个早期阶段测试所有系统和子系统接口以及系统性能至关重要。 系统功能和特性的测试不会在原型上进行。 5

该计划还包括任务描述、里程碑日期和可交付成果列表。

销售和营销内容

公司依靠技术作家来帮助销售他们的产品。 开发人员了解产品特性和功能的详细信息。 销售和营销团队需要以诱人的方式传达这些功能。

技术作家可以缩小这一差距。 他们可以获取技术含量高的产品文档，包括详细的规格，并使其与潜在买家相关。 这需要了解销售最佳实践并了解所涉及的技术。

产品描述等较短的营销资产通常是文案的领域。 但是当内容更深入，需要对产品功能进行更详细的描述时，就需要技术作家来完成这项工作。

白皮书

白皮书是关于常见痛点或行业问题的深入报告或技术文章。 它们具有教育意义和说服力，通常以公司的产品为中心，作为该问题的可靠解决方案。

企业制作白皮书以展示专业知识和思想领导力。 白皮书需要进行彻底的研究，并包含有价值的信息，包括超出显而易见的事实和统计数据。

大多数白皮书读者都熟悉相关行业。 他们希望这些材料能够为他们提供对问题的新见解，并且比典型的在线文章更深入。

熟练的技术作家可以提供这种深度，同时保持文章的可读性和趣味性。 技术白皮书内容丰富，但仍应以连贯的叙述吸引读者。 例如，本白皮书解释了有效排除软件故障的新技术的好处：

因为探针是用 C 或 Java 编写的，所以您可以编写探针来做这些语言可以做的任何事情，包括在您自己的应用程序中调用函数、在第三方应用程序或共享应用程序中调用函数——甚至检查和修改计算机的寄存器。 这意味着您可以检查或更改缓冲区的内容、获取和设置属性、触发异常或错误条件、收集计时统计信息、启动线程和进程等等。 6

编写这样的白皮书需要技术知识和简明扼要地呈现这些知识的能力。 即使是技术专业人士也能更好地参与故事而不是技术规范列表。 一份好的技术白皮书可以做到这一点。

实例探究

案例研究展示了公司的产品如何解决问题或满足需求。 他们从头到尾讲述客户旅程的故事，从将他们带到赞助公司门口的痛点开始。 结构涵盖：

• 问题描述
• 客户尝试的其他解决方案以及为什么它们不起作用
• 是什么将客户带到了赞助公司
• 公司如何解决问题
• 可衡量的结果
• 为什么解决方案有效

案例研究面向有类似问题的潜在客户。 如果写得好，案例研究可以帮助读者了解他们如何从公司的产品或服务中受益。

与白皮书一样，案例研究需要了解行业、问题和解决方案的作者。 作者需要了解过程并能够识别要点，如下例所示：

在应用程序迁移的同时，DPS 设计并部署了一个 Azure 云环境来托管客户端的域、打印和文件服务器。 虽然此解决方案在 Azure 中，但 DPS 仍将其设计为包含适当的备份和灾难恢复解决方案。 迁移到 Azure 云也是无缝的，因为 Azure 环境是在员工使用他们的本地系统的同时构建和测试的。 7

这种技术含量高的内容简洁而有意义地展示了服务的价值。 读者会相信赞助公司的专业知识和解决问题的能力。

提案和提案请求

当一家公司有一个即将到来的项目时，提案流程可以帮助它找到合适的合作伙伴。 运行该项目的公司将发布一份提案请求 (RFP)，其中描述了该项目及其范围。 此示例要求承包商进行信息系统安全风险评估：

预计将每年进行一次评估，初步评估涵盖整个 SSP（18 个对照组）。 此初步评估将利用 2020 年第一季度执行的渗透测试。随后的年度评估将包括 SSP 中包含的控制组的已识别子集，以便在 3 年内完成完整的控制组评估。 作为正在进行的评估的一部分，渗透测试将每年进行一次。 这是一种首选方法，供应商提交的文件指定了建议的解决方案。 8

RFP 的受众是知识渊博的，因此该文档可能是高度技术性的。 如果读者觉得有资格申请，他们会对 RFP 做出详细的建议。 成功的提案包括：

• 满足请求者需求的计划
• 选择提议者的优势
• 提供的服务清单和相应的费用

该提案是一份有说服力的文件。 它需要赢得潜在客户的信任，并将提出建议的公司作为最佳选择。

通常，技术公司需要向另一个行业的客户推荐其服务。 该提案需要在不恐吓或混淆读者的情况下展示专业知识。 技术作家具有独特的资格来完成这项具有挑战性的任务。

研究和报告

技术作家还与科学、工程和医学等领域的学术研究人员合作。 这些专业人士是各自领域的专家，但可能不善于交流他们所知道的。

技术作家是合成高级复杂材料的专家。 他们通读研究人员的发现，并利用他们所学的知识来制作清晰的信息内容。 该内容可能出现在学术期刊中，或者面向更广泛的目标受众。

例如，学院和大学经常报告关键教师或学生的研究。 技术作家可以用非技术读者理解的方式来描述这项工作，而不会“贬低它”或失去令人印象深刻的发现的影响。 以下是麻省理工学院新型机器人抓手的一个示例：

抓手由两个灵活的鳍射线手指组成，它们符合它们接触的物体的形状。 手指本身是由在 3D 打印机上制成的柔性塑料材料组装而成，这在该领域是相当标准的。 然而，通常用于软机器人抓手的手指具有贯穿其内部长度的支撑横梁，而 Liu 和 Adelson 将内部区域挖空，以便为相机和其他感官组件腾出空间。 9

作家还可以帮助科技公司向商业受众描述他们的作品。 技术作家可以通过获得资金并让项目保持关注的方式来传达这项工作。

高质量技术写作的重要性

在当今超连接的世界中，技术作家是必不可少的。 他们教人们如何使用他们最喜欢的电子产品，并使机器可供目标受众使用。

对于企业来说，技术作家是开发人员和受众之间必不可少的中间人。 他们的技术写作技巧将产品交到用户手中，提高了每个产品的可用性，使其对消费者和公司更有价值。 考虑这些重要的好处：

可靠的用户成功

高质量的文档帮助用户实现他们的目标，减少混乱和寻求帮助的需要。 用户可以快速准确地完成任务，而不是浪费时间弄清楚某件事是如何工作的。 用户感觉更成功，这提高了产品的声誉并提高了市场竞争力。

成本更低的技术支持

当用户可以独立操作产品时，他们在电话上与制造商或开发人员的时间就会减少。 这样双方都省钱。 用户可以更快地完成工作，公司因故障排除而损失的支持预算更少。 这笔钱可以转而用于创新新功能或促进客户成功。

更强的安全记录

产品文档通常包括安全建议和警告。 它们帮助制造和仓库专业人员安全地操作复杂的机械，减少受伤的可能性。 如果有效，这些安全警告可以减少代价高昂的诉讼和工人的赔偿要求。

安全警告还有助于消费者公司避免诉讼和负面新闻。 以下是 2021 RAV4 Prime 说明手册中的一个消费者警告示例：

检查后操作电动车窗或天窗或全景天窗，确保任何乘客的身体部位均不会被车窗或天窗或全景天窗夹住。 此外，请勿让儿童操作机械钥匙。 儿童和其他乘客可能会被电动车窗或天窗或全景天窗夹住。 10

像这样的警告可以保证家人的安全。

更大的受众和更好的销售

您知道您的产品可以改变用户的生活。 技术作家以最大的影响力传达该信息，帮助您吸引更多客户。

实现的新想法

投资者和高管不资助技术规范。 他们资助激发购买的用户利益。 技术作家可以以与非技术观众产生共鸣的方式描述项目，帮助开发人员获得资金。

复杂技术简化

无论是什么项目，技术作家都会揭开技术的神秘面纱。 他们浏览规范和报告，提取对买家和资助者重要的信息。 通过以读者可以理解的方式传达这些信息，技术作家使产品感觉更平易近人并加强客户联系。

寻找最好的技术作家

一个熟练的技术作家是物超所值的，但他们并不总是很容易找到。 公司可以花费数小时仔细研究内部职位的简历或查看自由职业者的投资组合。 这段时间最好花在推进创新产品或进行销售上。

不要再花一分钟寻找完美的作家。 Compose.ly 提供专门与您的项目相匹配的预先审查的技术作家，因此您可以在没有压力的情况下获得最合适的人选。 您无需后勤麻烦即可获得高质量的内容，因此您可以专注于您的业务。