如何使用金字塔结构来写一篇技术文档

技术人员都知道一篇好的技术文档的价值(这里换个表述),但是如何去写好一篇技术文档却一筹莫展。然而,在咨询业的传奇公司麦肯锡中,有一种叫做 ‘金字塔原理' 的写作方式可以快速的组织一篇结构化的文章。那么我们是否可以用 '金字塔原理' 来写一篇技术文档呢?

我们写技术文档的目的

对于软件来说,最重要的两点莫过于速度和质量了。写技术文档到底能不能提高软件研发速度不好衡量,但绝对可以提升软件研发过程的质量。软件的质量反映的是人类程序员的思考深度,而所有人类程序员都有如下两点先天限制: 缓存不足、上下文不同。

人脑的灵活性让我们有很高的创造力,但是在处理大型问题的时候却很难记住所有细节逻辑。所以将发散的思路梳理好并且记录下来这个过程,不仅可以帮助我们做好系统性的设计,还可以在设计阶段排除很多不必要的风险。简单来说就是: “高配 CPU 带小内存,你需要额外的空间来干活” 。

多人协作中,信息的传达效率以及信噪比是非常重要的。举个例子:我们知道在软件研发领域,英语是事实上的标准编程语言,但是在不同的业务场景中 "prod" 这几个字母的意思可能是 ”product“ 、”produce“ 、“producer” 这几个计算机领域常见词之一。文档的另一个核心作用就是: 显式固化只有开发人员才知道的隐性知识无论是缩写还是简写只要团队约定好字符串与实体的映射,那么整体沟通成本将明显下降。关于这一点,埃里克在 领域驱动设计) 这本书中有着精彩的论述,这里就不赘述了。

总的来说,写技术文档可以帮助我们作出更好的设计、显式固化隐性知识,从而提升软件研发的质量。

金字塔原理

我们用一些篇幅说明了文档和软件质量之间的联系,下面我们就来介绍一下金字塔原理。金字塔原理是一种突出重点、逻辑清晰、层次分明的思维方式,也是一种有效的分析问题、得出解决方案的有效工具。

01

作者在书中提供了一种金字塔式的文章组织方式,用来阐述有逻辑关联的事务,而软件正是不同事务变化时逻辑固化在硬盘上的表现,所以我认为用金字塔原理这种方式来写技术文档是再好不过的选择。

关于对金字塔原理的理解,可以选择看完《金字塔原理》的前三章,或者是通过我摘抄的作者对金字塔原理的解释来做初步了解:

  • 对受众(包括读者、听众、观众或学员)来说,最容易理解的顺序是: 先了解主要的、抽象的思想,然后了解次要的、为主要思想提供支持的思想。因为主要思想总是从次要思想概括总结得出,文章中所有思想的理想组织结构也必定是一个金字塔结构一一由一个总的思想统领多组思想。在这种金字塔结构中,思想之间的联系方式可以是纵向的( vertically)ー即任何一个层次上的思想都是对其下面一个层次上思想的总结;也可以是横向的( horizontally)-即多个思想因共同组成同一个逻辑推理过程,而被并列排在一起。
  • 受众的大脑只能逐句理解作者(演讲者、培训讲师)表达的思想。他们会假定一同出现的思想在逻辑上存在某种关系。如果你不预先告诉他们这种逻辑关系,而只是一句一句地表达你的思想,读者就会自动从中寻找共同点, 将你所表达的思想归类组合,以便了解各个组合的意义。

金字塔原理应用到技术文档写作的流程

02

时时刻刻,必须要提醒你自己:读这篇文档的人类是个缓存很小单线程图灵机,爆栈你就破功了,老弟/妹!

前面讲了很多理论性的东西,那么我们如何将理论与实践结合起来呢?下面分享一下我个人写技术文档的结构:

  1. 核心目标:金字塔的尖顶

    这里是金字塔最耀眼的尖顶,只写最核心的目标,比如说:调研某种技术方案、依照某个 PRD 开发产品部分功能。具体行文思路可以参照 《金字塔原理》 第4章— 序言的写法

  2. 方案概要设计: 金字塔的腰部

    这里是整体方案的蓝图,概要的抽象程度一定要很高,在这里必须可以看到全部架构。文字表述不清楚的地方可以多画图来辅助表达:

    1. 建议使用流程图用来表达状态流转
    2. 建议使用时序图用来表达交互顺序
    3. 建议使用C4 用来画系统架构
  3. 详细技术设计:金字塔坚实的基础

    详细设计部分是对上面概要设计的填充。这里是发现问题的黄金时间,一定要做很细致,需要有数据结构和关键逻辑的伪代码。细节设计做好之后,代码也写完三分之一了,剩下的就是写代码、写测试了。

  4. 维护:金字塔墙面砌砖与补漆抛光工艺

    根据我们上面对写文档目的的论述,文档不是一次性设计消耗,我们需要在开发有调整的时候,即时回来调整文档。举个不恰当的例子:汽车建造过程中刹车和油门换了位置,说明书总是要更新的吧。还有需要注意的一点就是: 当前文档只对当前版本负责,新版本不要在旧的文档上直接修改。

    03

这篇文章用了哪些金字塔原理中的方法

  1. 序言 :这里使用了 《第四章: 序言的常见模式》 中,背景-冲突-疑问 的三段模式,来隐晦的告诉读者可以用金字塔原理来写技术文档
  2. 金字塔原理应用的内容部分是用 顺序推理的方式来演示如何写技术文档

04

  1. 这篇文章的整体结构是归纳的方式

05

结语

金字塔原理是一套非常高效的结构化思考、表达工具。除了用来写文档,作者在书中也列举了很多其他应用场景,比如说:如何将 金字塔原理应用在做 PPT 上,如何用金字塔原理来分析问题等等。推荐各位仔细品读。

标签: none
返回文章列表 文章二维码
本页链接的二维码
打赏二维码