什么是模块化写作

模块化写作（英文：Topic-based authoring 或 Topic-based writing）是一种以主题（英文：Topic）为模块进行内容创作的写作方式，是编写各类技术文档是最常用的方式之一。这种写作方式与当前线性的写作方式形成鲜明的对比，各个不同的主题模块会根据不同的内容来自由组合或重用，每个主题是一个独立的内容模块，包含标题和内容（有时可以只有标题）向读者提供一段完整的信息。各个主题之间可以互相嵌套，也可以独立存在。根据结构化资讯标准促进组织（OASIS）发布的达尔文信息类型架构（DITA）规范，主题可以分为概念、任务、参考、术语表和故障排查五种类型。

简单来说，模块化写作就是写出一个个独立的内容模块。“独立的内容模块”可以是一个标题加上几段话，也可以仅仅是一个标题。它的评价标准也很简单：如果这段内容单独成文依然合乎情理，那它就是一个“独立的内容模块”。

举例而言，这篇文章《模块化写作》就是一个独立的内容模块。我既可以把它单独作为一篇文章、仅解释什么是模式化写作，也可以把它作为其它文章中的一小节、把模块化写作作为背景知识介绍给读者。无论哪种方式都是合乎情理的。

为什么要进行模块化写作

模块化写作的优点显而易见。

提升阅读体验。现如今，读者在搜索信息时所得到的信息多是碎片化的，用户需要自行整合信息以构建完整的逻辑体系来解决实际问题，这样做既费时又费力。模块化写作的目的就是让一篇文章自成体系——读者只要按照文章所列的步骤操作，就能够解决他所遇到的问题。
便于内容重用，降低维护成本，保证版本一致性。同一段信息可能出现在多篇文章之中；如果我们将这些信息存储在一个内容模块中集中维护，则会大幅减少维护成本。举例而言，以后我还会具体写到某些模块的写作方法，这些文章都需要先将模块化写作作为背景知识介绍给读者。因为我已经写好这篇《模块化写作》，今后我在其他文章中就可以直接引用这部分内容而无需逐字逐句复制粘贴。同时，日后如果需要修改这部分内容，我也只需修改这篇文章即可、无需修改其他文章模块化写作部分的内容，既避免了重复劳动，也避免了因为忘记修改某些文章而造成版本不一致的情况。
便于多人协作，提升工作效率。不同的内容模块由不同人员负责创作和维护，大家各司其职、互不干扰，避免了因多人共同修改同一文章导致的写作风格不统一、逻辑混乱和误操作等问题，提高了协同工作的效率。

模块化写作可以分为几种类型

内容模块可以分为不同类型，即不同“主题（Topic）”。不同Topic有不同的写作方法。

这些Topic包括：

任务（Task）
阐述完成一个特定任务所需要的步骤。比如一些类似于《X步用PS换图片背景色》的文章就属于“Task Topic”。
概念（Concept）
提供有助于读者理解有关产品、任务、流程或任何其他概念的背景信息。比如本文“什么是模块化写作”就是一个典型的“Concept Topic”。
参考（Reference）
提供给读者详细信息。比如在API文档中，每一段API信息就是一个“Reference Topic”。
术语表（Glossary）
提供基本术语信息。比如在一些文章的后面会列出这篇文章中出现的所有专业术语和它的解释，这就是典型的“Glossary Topic”。
故障排查（Troubleshooting）
描述系统、产品或服务出现故障的条件、原因和补救措施。比如一些服务网站中通常会有“常见问题”一栏，这一栏中每一个问题及其补救措施就是一个“Troubleshooting Topic”。

模块化写作如何应用

模块化写作是技术文档最常见的写作方式之一。很多IBM技术文档都体现出模块化写作的思想。接下来，我们一起分析一下模块化写作在《将私有 Ethereum 区块链部署到 IBM Cloud Kubernetes Service》一文中的应用。显然，这篇文章是基于任务（Task）的模块化写作。

这篇文章的结构如下：

题目（有时还含有一个副标题）必要
概览必要
学习目标
前提条件必要
预估时间
步骤必要
结束语（后续操作）必要
参考资源
评论

在这9部分中，1、2、4、6、7是必要的；3、5是可选的，要看具体公司写作风格的要求；8、9不涉及内容创作。现在，我们将必要的1、2、4、6、7这五个部分拆解一下。

第一部分：标题

对于模块化写作而言，一篇文章的题目是至关重要的。一方面它概括了文章的主要内容、便于读者通过关键词搜索和定位；一方面它限定了文章内容的范围。这就要求在标题中点名关键词，让标题能够准确反应文章内容——没有夸大或缩小文章内容。

这篇《将私有 Ethereum 区块链部署到 IBM Cloud Kubernetes Service》的标题就点名了三个关键词：私有Ethereum、IBM和Kubernetes。它既点名了文章的三个主体（当读者查找这三个关键词时很容易定位到这篇文章），又限定了文章讨论的范围（试想，如果将标题换成《将区块链部署到 IBM Cloud Kubernetes Service》，则会有很多希望将Hyperledger Fabric区块链部署到IBM Cloud Kubernetes Service的读者也会阅读这篇文章，结果浏览全文之后却发现根本解决不了他的问题）。

此外，本篇文章还有一个副标题：有关如何将私有 Ethereum 区块链部署到 IBM Cloud Kubernetes Service 的分步指南。“分步指南”这四个字进一步说明了文章的内容——这是一篇实操类的文章、不是一篇介绍类的文章，如果你需要解决实际问题，就请放心读下去吧！

第二部分：概览

这部分是要进一步解释标题的含义，并对全文进行一个简要概括。它可以包括以下内容：

解释标题中出现的关键词
进行背景介绍或讲述背景故事
简述文章总体的结构
说明文章的用意

它的存在是一篇文章得以独立成文的关键。一方面，有了它，读者无需查找上文就知道这篇文章所需要的全部背景知识；另一方面，它进一步限定了文章的边界，详细地告知读者这篇文章讲了什么，让读者对于“这篇文章能否满足自己的需求”有了一个合理的预判。

这篇《将私有 Ethereum 区块链部署到 IBM Cloud Kubernetes Service》的“概览”一节就解释了标题中出现的关键词：Ethereum 和 IBM Cloud Kubernetes Service。

第四部分：前提条件

既然前面的标题和概览限定了文章的边界，也就意味着有一些准备工作需要读者事先完成。这一部分就是要提醒读者，在完成这篇文章所讲述的步骤之前，您还需要具备哪些条件。对于那些不满足条件的读者，要帮助他们满足条件；因此，很多时候，我们还会在这一部分提供相关参考文档的链接供读者阅读。

回到这篇《将私有 Ethereum 区块链部署到 IBM Cloud Kubernetes Service》。让我们把这个题目抽象一下。这篇文章讲的是如何将A部署到B，那么它的前提条件必然是已经有了A和B。因此，这篇文章的前提条件就是要有Ethereum（安装Geth）和 IBM Cloud Kubernetes Service（安装IBM Cloud CLI、Docker、he Kubectl）。同时，这篇文章也提供了相关参考文档的链接。

第六部分：步骤

这是文章中最重要的部分。它具体讲述了解决问题的方法。因此，要做到以下几点：

按操作的先后顺序列出步骤
用动词明确操作内容，具有可执行性
语言简洁无歧义
最好采用统一的句型

如果单一步骤超出一句话，则请设置步骤标题，再具体解释步骤内容。

请看这篇《将私有 Ethereum 区块链部署到 IBM Cloud Kubernetes Service》所列出的步骤大纲（在文中，每一个步骤下面都有详细的操作说明）：

构建 Docker 镜像
将 Docker 镜像部署到 IBM Cloud Kubernetes Service
在 IBM Cloud 上创建容器服务
设置您的容器
将镜像从您的机器推送到 IBM Cloud Private 注册表
将您的镜像部署到 IBM Cloud 上的 Kubernetes 集群
测试您的专用 Ethereum 区块链

首先，这些步骤是按照实际操作的先后顺序列出的；第二，请看加粗的字体，这些动词成功地吸引了读者的注意力，语言简洁有力，具有可执行性；第三，基本上采用的是统一的句型，即：（其他成分+）动词+名词。

第七部分：结束语（后续操作）

通常，这一部分会首先总结一下本文的成果，再介绍后续操作。前者提升了整篇文章的完整性；后者提升了解决方案的系统性、指引用户更深入地使用产品。

结束语

感谢您阅读这篇《模块化写作》。如果您有我以后将会具体讨论不同模块的写作方法。敬请关注。

欢迎您对模块化写作和本文提出宝贵意见：iamsuez@163.com

参考文献

维基百科, https://zh.wikipedia.org/wiki/%E6%A8%A1%E5%9D%97%E5%8C%96%E5%86%99%E4%BD%9C
The IBM Style Guide: Conventions for Writers and Editors, Chapter 4, “Structure.”
Saif Rehman, “将私有 Ethereum 区块链部署到 IBM Cloud Kubernetes Service,” https://www.ibm.com/developerworks/cn/cloud/library/deploying-ethereum-blockchain-to-ibm-container/index.html

模块化写作（Topic-Based Authoring 或 Topic-Based Writing）相关推荐

基于身份的加密（IBE）——使用PBC库实现 Identity Based Encryption(IBE) - Pairings Based Crypto (PBC) library
基于身份的加密(IBE)--使用PBC库实现 Identity Based Encryption(IBE) - Pairings Based Crypto (PBC) library 前言: 近期在学 ...
kafka 基础概念、命令行操作（查看所有topic、创建topic、删除topic、查看某个Topic的详情、修改分区数、发送消息、消费消息、查看消费者组、更新消费者的偏移位置）
文章目录前言 1. 基础概念 Broker Producer Consumer Consumer Group Topic Partition Replica 2. 命令行操作 2.1 查看所有top ...
英语课topic计算机,英语中,topic和theme有何区别?最好能举例说明.举例越详细,追加分数越高....
这两个单词差异很大. theme: A topic of discourse or discussion. 题目:论文或讨论的题目 A subject of artistic representati ...
电商分类模块写法_模块化写作——网络小说创作之典藏秘籍
1.模块化,是一种将复杂事物分解为多个模块,从而获得效率与质量的操作手段.这个概念常出现在与科技相关的领域里.其实,模块化在文学领域里也很重要. 例如,小说的情节被分解为四个模块:开端.发展.高潮.结 ...
【kafka】kafka 消息重放从一个 topic 导入另外一个 topic
1.概述参考:官网重放脚本 [lcc@lcc ~/soft/kafka/kafka_2.11-1.1.0]$ bin/kafka
topic是短语还是句子_topic是什么意思_topic怎么读_topic翻译_用法_发音_词组_同反义词_主题-新东方在线英语词典...
词汇搭配用作名词 (n.)动词+-avoid the topic避开话题 bring up a topic把题目提出来讨论形容词+-the key topic关键的论题介词+-write on th ...
ROS2入门教程—理解话题（Topic）
ROS2入门教程-理解话题(Topic) 1 启动小海龟仿真器 2 rqt_graph 3 ros2 topic list 4 ros2 topic echo 5 ros2 topic info 6 ...
【带你玩转主题模型Topic Model】—— 之利用sklearn 实现Latetnt Dirichlet Allocation(LDA)主题模型
写在前面的话 9月份的第一篇blog, 正好是开学季,作为一个学生,hahahha, 我还是正正经经的贡献一篇认为比较干货的文章给大家吧. 我自己是花了很多时间去看懂LDA的算法了,当然了这篇文章不涉 ...
Kafka如何对Topic元数据进行细粒度的懒加载、同步等待？
首先确保Topic的元数据可用,否则消息根本没法往外发.如果以前从没加载过Topic元数据,就会在doSend发送消息时调用waitOnMetadata方法在此同步阻塞住,等待连接Broker成功后拉 ...

模块化写作（Topic-Based Authoring 或 Topic-Based Writing）