构建文档

引言

本文介绍了一种简单的方法，用于解决中小型企业在技术文档中最常见的难题之一：在文档系统中组织信息结构。

该方法在许多情况下可以

• 让那些需要提供信息或编写技术文档材料的人的生活更轻松
• 大幅降低信息管理的开销
• 使技术文档中的信息更易于访问，从而减少向沮丧的用户亲自解释事物的所需时间

这些都不是营销式的宣传。我引入该方法的地方都取得了这些效果。

（不过，这有点推脱责任，因为我只在我知道它会带来巨大改进的地方引入过它。）

有趣的是，该方法从未被命名，因为

• 直到现在，它都未曾需要一个名字。我亲自向所有需要它的人演示过，并且很少写过关于它的内容。
• 所有使用它的人都知道它有多简单，并且以这种方式工作有多么显而易见，所以我从来没有想过给一个如此简单和显而易见的东西命名。

然而，现在它要在互联网上“公之于众”，在几十万“求代码！”的优越生物们等着为他们在网上看到的一切申请功劳的地方，我将通过懒惰地称它为“华莱士方法”来讽刺整个“有意义的名称”的模式。

著名的软件公司 Gliebules and Daughter 欣然允许在其名称、产品和流程中用于本文。

1 技术文档的背景

这里有一个人生（尤其是在技术文档方面）的绝佳准则

在你出发去任何地方之前，确保你知道你在哪里。

1.1 文档流

你的公司可能拥有多个产品文档流，不仅仅是技术文档——例如，通常有一个用于市场营销文档（用于销售产品时）的流，以及另一个用于内部文档（用于设计/讨论产品时）的流。

每个流都有其自己的存储结构、文档库等，而技术文档的要求通常是最复杂的，因为它们包含的信息量最大。

关于文档流，有两点很重要

• 来自一个文档流的文本很少能在其他文档流的文档中使用，因为每个文档流的读者要么是不同的人，要么是出于不同目的阅读的相同人。

举例说明：如果你正考虑购买一台录像机，你不会关心你需要按哪些按钮来设置它以录制你喜爱的肥皂剧；你只想知道它的功能。你需要的是市场营销信息。

当狗狗把遥控器埋了，而你正跪在地上试图设置那个该死的机器时，你最后想读的就是告诉你它功能的内容。你需要的是技术信息。

• 图表、截图和图形在不同文档流之间具有很高的可移植性，所以请确保每个人都能找到你制作的所有精美图像文件——重复绘制同一张图表的时间就是浪费的圣诞奖金。

1.2 技术文档的视角

现在，我知道你是一名开发人员，因此是房间/星球/银河系/跳蚤马戏团里最聪明的人，但你仍然可能需要稍微调整一下技术文档的视角。

对于技术文档来说，唯一有效的视角（没错：只能有一个）可以通过遵循以下过程来演示

1. 打印出你公司制作的所有技术文档的硬拷贝。
2. 将它们全部堆成一堆，一张叠在另一张上面，按照你认为合适的方式排序。
3. 在文字处理器中，打开你的标准文档首页模板。
4. 在标题所在的位置，输入文字：“我们的产品”。
5. 打印出该页面的硬拷贝。
6. 将其放在技术文档堆的顶部。
7. 如果有人问你公司有多少技术文档，指向那堆文件，然后说：“一本”。

明白了吗？

你只有一本技术文档，它涵盖了你公司制造的每种产品的每一个细节。

为了方便大家，这一本文档被切成了更小的部分，每个部分独立制作和分发，每个部分专注于“你的产品”的一个或多个特定元素。

为了混淆大家，我们也把这些部分称为“文档”。

这是唯一有效的视角。（我见过所有其他的视角，很多次，并且听过所有借口）会导致不必要的问题、工作和开销。

1.3 错误视角带来的麻烦

让我们来看一个例子，说明缺乏正确视角会带来什么结果。

1.3.1 Gliebules and Daughter 的情况

Gliebules and Daughter (G&D) 是一家大数据公司，拥有五个主要软件产品

• G&D 的 Data Pipelinifier（数据管道器）能从任何指定的地方吸入大量数据。
• G&D 的 Data Transmogrificator（数据转换器）转换吸入的数据。
• G&D 的 Data Jajahardericator（数据详述器）是一个可选产品，用于处理转换过的数据。
• G&D 的 GoodLooki 是一个内部构建的用户界面，允许用户处理他们的数据。
• G&D 的 MeGodOk 是一个用于控制这一切的管理界面。

从这个宏观概览来看，很明显这五个产品共同服务于一个目的：将数据从某个地方获取并提供给客户。

G&D 的问题在于，每个开发部门在编写文档时各自为政，将他们的产品记录得好像它们是独立的东西一样，但正如我们所见，它们显然不是。

我们正确的视角不是 Gliebules and Daughter 所使用的视角。

1.3.2 在 Gliebules and Daughter 使用错误视角的影响

简要查看 G&D 的技术文档，发现 Pipelinifier 用户指南中有一个部分描述了 Transmogrificator，Transmogrificator 文档中有描述 Pipelinifier 的部分，而 Jajahardericator 文档中超过一半的内容都在解释其他一切是如何工作的。

这是完全可以理解的。如果你让某人坐下来对他说：“记录你的工具！”，他可能会花费更多时间研究和记录其他东西，因为他知道他的工具是如何工作的，他认为其他东西才是需要解释的难点，所以他把它记录在当前位置，而不是正确的位置。

这是“我们需要什么都有，到处都是”和“在光标所在处输入”综合症的结合，这两种情况都非常普遍。

因此，在 G&D，公司各处的人们都在不同的文档中用不同的词语记录相同的内容，而产品更改的文档更新成了一个笑话，因为没有人知道当产品更改时，有多少（或者即使是哪些）文档需要更新。

更糟糕的是：人们有时知道某件事情在其他文档中已经记录过，所以没有将其包含在自己的文档中——而这本该是信息应该在的唯一地方。

这给 G&D 的客户带来了严重的问题

• 他们找不到所需的信息，因为它散落在各处。
• 当他们找到看起来有用的东西时，一半的时间它都无法正常工作，因为它被错误的人记录在了错误的地方，而且从未更新过。
• 一些客户得出结论，他们无法信任任何文档。

这导致 G&D 的客户支持需求像吸血鬼一样吞噬着开发团队的生命。

换句话说：对于文档来说，这是一个非常正常的情况。

哦，如果你还没猜出来，这非常类似于我曾为几家公司解决过的极其相似的情况。

1.3.3 Gliebules and Daughter 问题发生的原因

G&D 的混乱情况，在不同程度上，在许多许多软件公司中都存在，从最小的到最大的。

经过多年来为解决文档问题以及客户支持成本问题而抓狂，我得出了几个不可避免的结论

• 技术文档中不良的信息管理是会花费金钱的。
• 技术文档中不当的信息管理是会花费金钱的。
• 良好、恰当的信息管理在技术文档中可以节省一大笔钱。

细想一下，这不是很明显吗？

既然如此明显，为什么没有人去做呢？ 为什么我必须离开家，飞遍全球去指出并解决这个“显而易见”的问题？

嗯，我总会发现，文档很少被视为 G&D 等问题的根源。聪明人甚至问我，如果问题是客户支持成本过高，为什么我要谈论文档？

“显而易见”是如何丢失的

• 在花费时间用错误的方式把某事搞砸后，客户会打电话给支持部门。
• 他会尖叫：“它不工作！”（或者他可能小声说；因人而异。）
• 他要求立即解释为什么他笨拙的尝试不起作用。
• 然后他要求让程序按照他尝试的方式工作。
• 在所有（通常是充满敌意的）讨论和疯狂的修复活动中，有人随意提到文档没有帮助，但每个人都忽略了他。

在随后赶着让事情按照客户临时决定的方式工作时，没有人认识到，如果文档够好

• 客户本应按照产品的设计方式使用它。
• 它本来是可以工作的。
• 工作队列中不会添加任何 P1 级别的变更请求。P2 或 P3 到 P99 级别也不会。没有人需要做或改变任何事情。

“哦，我们有一份文档。这就够了！”的心态非常普遍。文档的质量和可用性被设定为零优先级；所有重要的是它的存在。

试着用同样的态度对待代码，看看能走多远

“我们有一些代码。它只是由一群人随意拼凑而成，他们没有就此进行沟通，它没有做任何它应该做的事情，而且它会朝着它不应该去的方向发展，但客户最终会把它丢到一边然后忽略它，所以没关系。发布吧！”

2 华莱士方法

我将长久地回味这个名字——这是一种无意义、无信息的名称，而这种方法本身不允许这种情况。

2.1 目标

华莱士方法的目标是处理你所有混乱的信息，无论写得好坏，并引导你进行组织。你的信息仍然会写得好或坏，但至少它会被组织起来，这意味着

• 读者将能够找到他们需要的信息。这将大大减轻你支持团队的压力。
• 贡献者将知道将新信息放在哪里，以及更新现有信息放在哪里。你可能会惊讶于这可以减轻那些必须在文档中添加或更新信息的倒霉蛋多少压力。

2.2 要求

华莱士方法的唯一要求是人脑。

文档中的信息是人们需要的，而不是计算机；它必须被人们理解，而不是计算机。

因为计算机不理解你写的内容，所以它们不是真正有效信息管理的错误工具，而信息管理需要对信息有理解。

因此，如果你是一家中小型公司，没有特殊的文档需求，管理信息只需要人脑。

……当然，还有阅读能力，但考虑到我正在向你传达这些信息，我想我们可以假定你具备读写能力。

2.3 华莱士方法唯一的一条规则

是的，你没看错标题：华莱士方法只有一条规则。

如下所示

规则 1：添加到文档的任何内容必须完全与其前面的最近标题相关。

看我说的显而易见了吧？

这里有一张图

所以，我们有“标题级别”和“语言级别”。

1. 在标题级别，标题下的所有内容都必须与整个标题有关——不一定是整个标题，但仅限于标题。
2. 在语言级别，每一个词、短语、句子和段落都必须致力于提供关于其上方最近标题主题的信息。

这简直太简单和显而易见了！

我为什么要用这些简单而显而易见的废话来浪费你的时间？

原因如下

练习 1

拿起你的一份技术文档，看看是否应用了极其简单和显而易见的规则。

1. 你的标题/头是什么样的？ 很容易看出每个章节/部分是关于什么的吗？ 你能仅仅通过阅读标题就确切地知道每个部分必须包含哪些信息吗？
2. 检查目录（如果有的话；如果没有，就按部就班地做）。你能看到每个子章节的标题/头都是其父标题/头的一个合适的孩子吗？
3. 选择一个比较大的部分或章节，走到它的底部，然后倒着走，从子标题跳到子标题，检查标题下的所有内容是否完全与该标题相关。

在进行练习的过程中，你发现了多少潜在的改进点？

这就是我用这些简单而显而易见的废话来浪费你的时间的原因。

只需将一条规则铭记于心，再加上几个小时的时间，你就可以修复你文档中的大量问题——并标记出更多有待解决的问题。

2.4 华莱士方法如何运作

“信息”的定义是“有用的数据”，但只有人才能决定什么数据是有用的，以及它在哪里是有用的。位于错误位置的信息会被降级为“数据”状态，而人们不擅长阅读和处理数据（这可能就是计算机如此受欢迎的原因之一）。

华莱士方法依赖于对标题含义的阅读和理解。如果标题的含义不被理解，那么就无法填充其部分的内容。

计算机无法理解标题的含义，也不知道如何将你的想法和理念传达给其他人，所以你不能让它们为你管理信息。

基于计算机的应用的信息管理系统总是会变得过于笨重、受限且难以维护，因为为了弥补在使用系统时被视为人为错误的地方，你只能添加越来越多的、越来越复杂和令人困惑的规则，直到最终系统停止运转。

然而，即使是最愚蠢的人，也能做出价值判断，比如“嘿，这和那个没关系！”，所以让每个人都遵循那条（极其简单和显而易见）的规则，实际上可以几乎毫不费力地让信息不再处于错误的位置。

华莱士方法之所以有效，是因为它使用了你能够获得的最复杂的计算设备——你的大脑。它利用你的大脑来做它认为非常容易做的事情——对事物进行分类和关联。

为了进行所有这些分类和关联，你的大脑会使用海量的复杂而精密的规则，这些规则由你的知识和经验来管理。

以目前的技术，可能需要一百人年才能为计算机编写所有这些规则（再加上一百万年进行调试）。

但真正需要的是一些能让你的大脑将努力集中在正确的方向上。

嗯。

不如我们就给它一条令人难忘的（并且极其简单和显而易见）规则让它去遵循？

它就是能用。我应该把它放在一个极简图片加持的白盒子里。

2.5 实施华莱士方法

因为整个事情非常简单和显而易见，你可能可以自己弄清楚剩下的事情，但这里有一些建议

2.5.1 使用有意义的标题/头

还记得我们看到该方法之所以奏效，是因为人脑可以理解标题/头的含义吗？

好吧，如果你不使用有意义的标题/头，那就没有什么可以理解的了，所以你就成功地破坏了有史以来最简单、最显而易见的流程。

不要再犯了。

看看我在本文中使用的标题/头（这不是技术文档，所以我并没有真正遵循任何规则）。除了几个不需要更多文字的老标准（“目标”和“要求”）之外，你都可以根据标题/头的内容知道各个部分的内容。

想象一下，一个你可以打开任何技术文档，并使用目录来查找所需内容的世界，只需沿着清晰的标题/头轨迹，就能立即知道文档的哪些部分对你无关紧要。

一条规则，可以吗？ 只遵循一条规则。

2.5.2 如果一个部分标题与其内容不再匹配，就改变一些东西

产品会变化；随着内容的添加或删除，事物的规模会变大或变小，过程可能变得更复杂和迂回（或者，正如经常发生的那样，它们已经更复杂和迂回，但没人 bother 告诉你）。

显然，这会对文档产生影响，而产品的变化会让你觉得似乎永远无法将所有内容挤进正确的位置，带有正确的标题/头。

但看起来是这样。

它看起来像一个问题，是因为人类典型的对变化的厌恶——一旦你修复了文档中的所有问题，你所有的标题和内容都完美了，你为自己的成就感到自豪，你的大脑会抵制改变标题和内容的想法；它不想拆分内容，或者移除一个上周还很不错的标题，用两个不一样的标题替换它。

但你看：你是在电脑上创建文档的，所以改变东西真的很容易——如果需要的话，甚至可以改变一切——不像你必须废弃一打石板，再刻十五块来替换它们。

你可以拆分章节，添加章节，删除章节，或合并章节；你可以编辑标题，添加标题，或删除标题。没问题。

如果你甚至发现自己在用“挤”这个词，就开始寻找重组文档的方法，而不仅仅是添加新信息的方法（这是一种思维方式：“我正在重组文档”，而不是“我正在添加内容”）。

你所要做的就是确保你的新结构遵循一条规则，它就会有一个快乐的结局。

2.5.3 一直向上追溯

还记得我们必须对技术文档保持的视角吗？

那个认为只有一本文档被拆分成子文档的视角？

• “我们的产品”文档是阶梯的顶部。
• 每个单独的产品都是“我们的产品”的一个子部分。
• 每个产品子文档（用户指南、管理指南、帮助文件等）都是产品子部分的子部分。
• 产品子文档中的每个章节都是“我们的产品”文档的子部分的子部分的子部分。
• 依此类推。

整个东西就是一个大梯子，或者树，或者你想要如何想象它。

记住这一点。

并记住，还有很多其他文档包含一些内容，而这些内容可能比现在的位置更适合放在那里。

也就是说，如果你遵循那条规则，你就不能像 Gliebules and Daughter 那样，在你的文档的一个部分中描述如何使用另一个产品；你必须把它移到一个（在另一个子文档中）正确合适的部分。

这里的诀窍是，你不要在一个非转换文档中描述如何转换数据；你只说明你的产品需要经过转换的数据。

2.5.4 不要写两次；单一来源

再次阅读这句话

这里的诀窍是，你不要在一个非转换文档中描述如何转换数据；你只说明你的产品需要经过转换的数据。

“如果那还不够怎么办？”我听到你问。

当然，会发生。

有时你确实需要在你的子文档中包含其他产品的信息——有时只是一段，有时是一张表格，有时是整个章节。

在这种情况下，将所需的材料创建一个单一来源的主题/块，并将它放在两个子文档中。

你可能需要稍微修改一下文本，使其适合两个文档，并且你必须像税务一样确定你的标题/头使其非常清楚是什么，但这是完全可行的，如果你知道如何单一来源信息。

我在这里不深入讨论单一来源；也许以后。只是不要在你已有可以溯源的现有材料的地方撰写新材料，好吗？

有趣的是，我让你再次阅读的那句话：如果我用 FrameMaker 或 Flare 写这篇文章，我会将其设为单一来源。复制和粘贴并不总是你的朋友。

历史

• 2015 年 1 月 9 日：原始内容