# 关于技术写作 写作对大家来说并不模式，我们每天都会有很多写作任务，根据目的和读者的不同，常常有如下分类： + 创意写作（ Creative Writing ），打动人的心灵 + 文案写作（Commercial copy writing)，卖东西 + 商务写作（Business writing)，管理人员 + 科学写作（Scientific writing)，记录和分享科学发现 + 技术写作 (Technical writing)，解释工作原理、指导用户完成特定操作 其中，技术写作，与其他写作类型存在一个很大的不同：它不是一个文学上的概念，而更近似于一个工程学上的概念。尽管技术写作本身并不排斥文学上的创新与包装，但从更高维度来说，它一定首先是一个工程项目。因此，对于技术写作，必须从工程的角度出发，才可以避免写作时的南辕北辙，似是而非。 ## 从工程角度看待技术写作 技术写作作为工程项目，与其他很多领域有着复杂的交汇。尽管某种程度上技术写作的历史和人类的文字史一样长远，但早期的技术写作并不是一项独立的职业，往往由项目的负责人、产品经理（也许那个时代还没有产品经理这一具体职位），或者有丰富项目经验的一线工作人员负责完成。因此，技术写作领域很多名词、思想都是从其他工程领域借用而来，特别是软件工程领域为技术写作提供了大量的方法论作为指导。而最重要的是，它不仅与工程领域的学科有交汇，和管理学科也有着很大的关系。类似工程理论、质量控制论等学科都可以给技术写作注入严谨、科学的血液。例如，质量控制理论中的**PDCA(Plan-Do-Check-Art)**模型也可以应用到技术写作领域，能够有效提升技术文档的写作质量，提高写作人员的专业素养。 而所有和“工程”相关的学科都有共性，它们和各种“哲学”、“科学”的学科有着非常明显的区别。有人总结道： + 哲学家的宗旨是：我思，故我在 + 科学家的宗旨是：我发现，故我在 + 工程师的宗旨是：我构建，故我在 人类要生存，人类文明要向前发展，离不开思考、发现、构建。因此，当从工程的角度看待技术写作时，我们可以很容易就认识到最初的文档构建是整个文档写作的基石，它直接影响到了最终的文档呈现。 此外，不同的工程项目也有很多各自的特点： + Build To Learn：构建项目的目的是做进一步实验，试图发现客观规律或探求某方法的优劣 + Build To Show：突出地展现某个技术的作用，吸引眼球但是功能未必全面或实用 + Build To Serve：为服务一定范围的目标用户而构建的工具 + Build To Win：以在市场上赢得用户为目标构建的软件 技术文档写作项目，显然应该属于 **Build To Serve** 的范畴。它讲究用户的使用体验。因此，技术文档作为产品与用户沟通的桥梁，它与人的行为、现实社会的需求息息相关。如何做到以人为本，提高技术文档的写作质量，正是我们关注的重点。 ## 从“人”的角度看待技术写作 技术文档的写作目标（文档的开发、维护）中都有“人”的存在。与其他类型的写作不同，这里的“人”并不只有用户。这些“人”可以是产品需求的提供者，可以是产品的开发人员，可以是文档的写作人员，也可以是文档的读者（也就是产品的用户）。这一特征说明，提高技术文档的质量，并不只是针对产品面向的客户，同时也是针对其他的开发人员。而本文主要探讨的同源开发与内容复用策略，更偏向于提高产品开发人员与文档写作人员的用户体验。它的核心目的在于提高文档开发人员的工作效率，保证文档内容的一致性和可复用性，使其易于写作人员的维护工作。而用户则主要受益于单一来源带来的术语和信息的一致性。 ## 技术写作的对象 技术写作的主要对象为规格说明书（Specification，简称Spec），分为以下两种： + 产品功能说明书（Functional Spec），主要用来说明产品的外部功能和用户的交互情况（把产品视作一个黑盒子）。 + 产品技术说明书（Technical Spec），又叫设计文档（Design Doc），主要用来说明产品内部的设计规范（把产品当做一个透明盒子）。 ### 功能说明书 功能说明书从用户的角度描述了产品的功能、界面、操作流程、功能的边界问题、功能的效率（对用户而言）、国际化、本地化、异常情况等，不涉及产品内部的实现细节。 谁来写Spec？通常是项目的PM，或者是有一定经验的开发或测试人员。 谁来实现Spec？是开发人员、UX/IX设计人员。 谁又来验证Spec是否全部实现了呢？是质量保障人员（QA），可以由别的人员来实行，但必须要注意要从用户的角度来出发进行验证。 怎么才能写好一份Spec？这里我们不谈论同源开发的方法论，仅仅是从线性文档开发的角度探讨、总结这个问题： + 第一，定义好相关的概念 + 第二，规范好一些假设 + 第三，避免一些误解，界定边界条件 + 第四，描述主流的用户和产品交互步骤 + 第五，一些好的功能还会有副作用，要清楚地写明这些副作用 + 第六，服务质量的说明 写好Spec的秘诀不多，只有以下三点： > **实践，实践，再实践** Spec的另一个敌人是时间，几乎在Spec写好的那一瞬间，Spec就开始过时了。容颜易老，Spec尤甚，怎么办？ + 记录版本修订时间和负责人————这样出了问题好去找人。 + 在Spec中说明如何验证关于功能的描述，从Spec的描述中就能知道如何测试产品的功能。 + 把Spec和测试方式等内容交叉引用，互相连接 + 变化是一定会发生的，与其在Spec中有意忽略这一点，不如主动挑明哪些部分容易发生变化并提前做好预案。说明哪些部分如果发生了改变，会出现何种连锁反应。 + 在做任何改动的时候，一定要事先参考Spec，事后更新Spec，项目领导人不应该在没有Spec的情况下做拍脑袋的决定。 ### 功能说明书的模板 Spec有模板吗？似乎很多读者都有这样的希望，一旦搞到一种模板，事情就成功了一大半。事实上，这也是同源开发中最核心的思想之一：盲目套用模板对文档有着巨大的副作用。事实上，一种建立合理模板的方式，仅需将前文的内容简单总结即可得出： + Spec的目标是什么？Spec的目标不包括什么？ + Spec的用户和典型场景是什么？ + Spec用到了那些术语？它们的定义是什么？ + 用户是如何使用产品的功能的？ + 各种边界条件是什么？边界条件有很多，不同国家、地区、文化、语言、产品所处环境等等…… + 功能有什么副作用？对于其他功能有什么显性或者隐性的依赖关系？ + 什么叫“好”？什么叫“功能测试完毕可以交付使用”？ + 产品发布出去后，可以从哪些方面取得反馈？如何在产品开发阶段做好反馈的接受工作？ 也许读者已经发现了，我们成功地将一份技术文档按主题拆解成了很多的“模块”，而最终的文档似乎只需要我们搭积木一般将这些模块拼接就能得到。 ### 技术说明书 技术说明书又叫设计文档，它用于描述产品的开发者如何去实现某一功能或者是相互联系的一组功能。产品多种多样，放之四海而皆准的模板显然是不存在的，但是产品总是需要遵循一定的原则去设计与实现。我们这里以一个最常见的品类————软件产品为例，叙述一份技术说明书应当包含怎样的设计原则。毕竟，软件产品本身具有的复杂性、不可见性、易变性、服从性、非连续性等特性使得工程师如果不遵循一些设计规律，在后续的实现以及迭代过程中必然要吃苦头。也因此，软件产品特别适合作为典型代表在这里作为例子。 一份软件产品的技术说明书，应该说明工程师的设计是如何体现下列原则的： + 抽象 + 内聚、耦合、模块化 + 信息隐藏和封装 + 界面和实现的分离 + 如何处理错误情况 + 程序模块对于运行环境、相关模块、输入输出参数有什么假设？假设是否经过验证？ + 应对变化的灵活性 + 对大量数据的处理能力 + 高负载下的性能表现 以上都是一份合格的技术文档，应当具有的基本素质。本章看似没有讨论同源开发，但事实上这些对技术文档写作的质量需求，是同源开发这套策略和方法论的根本来源。没有这样的文档需求，同源开发技术也就不会孕育而生。 因此，下一章开始，我们将着重讲述什么是同源开发和可复用策略，以及如何在这套方法论的指导下完成文档的开发工作。