如何设计和使用文档模板 | 技术写作什么鬼

2024-02-26 15:00:46 浏览数 (1)

今天看到叶伟民老师的一篇文章,瞬间泪目:叶老师,您是懂人性的啊。在我整天鞭策自己“不能再拖了”的关键时刻,及时分享经验:

是的,这篇文章实在是拖了太久,了太久,太久,久……

书接:从0到1的模板插件 | Obsidian实践,有朋友提问说:你有现成的模板,可以分享一下吗?

针对这个提问,第一时间便起草文章,不过写着写着思路散了,便被搁置一边,拖延至今也没有完成……

所以,必须下定决心,花点时间理清思路,把这篇文章继续写完吧。


话说,Obsidian实践,属于个人知识管理的场景。个性化的经验,就很难被其他人直接复用。如果我们把场景,从个人知识管理,切换到日常工作中,信息场景往往会更加聚焦和典型。比如说,产品立场最常进行需求说明;研发立场主要关注概要设计;测试立场也少不了输出测试方案……那么在这种情况下,就比较容易总结、归纳既往经验,形成模板进行复用。

所以我们换个思路,聊聊如何在工作场景中,定义和使用模板。

为什么使用模板?

不过,在切入正题之前,还是想先形而上学地整点儿所谓的“意义”。是因为,

对于使用模板,可能存在一个比较普遍的错误认识:使用模板是应付写作任务的生搬硬套。

所以很多时候我们会发现出现这样的情况,即便是基于成熟的内容模板写作,最终输出的内容质量依然不太令人满意:对模板章节点内容理解错误;上下文缺乏逻辑关联;或者内容不连贯,不自洽的情况。以至于,原本我们希望通过写作梳理和阐述的问题逻辑,依然没能得到很好的体现。

我们通常会认为,模板是对内容和格式的复用。其实这还只是一个方面,更重要的是,模板本质上的体现的是典型的信息场景,其内容是对当前场景的经验和思路的积累和复用,以便高效沟通和解决问题

所以,无论是设计模板,还是使用模板,都需要聚焦在对问题逻辑的阐述上,才可以更好地发挥模板的作用。

如何设计模板?

设计模板的基本思路是:

  • 明确面向对象;明确信息目标。
  • 基于已有经验,梳理解决问题的思路;
  • 调研信息需求,使思考更加全面充分;
  • 结合上述两者,输出内容架构和写作说明。

首先,明确面向对象和信息目标,对于文档开发而言,是非常重要的。这一定程度上可以看作是“产品思维”的体现,在模板设计阶段,就尽可能聚焦于,典型信息场景要解决的具体问题。

接下来,我们基于已有经验,把当前场景中思考和解决问题的逻辑梳理清楚,这实际上也是对知识、经验进行总结和积累的过程。

为了便于与人沟通我们的想法,还可以通过信息调研、文档评审,或者日常沟通,收集多方的反馈和建议,不断充实完善我们的逻辑叙述。

当我们很好地梳理了自己的思考逻辑,并且充分了解了相关干系人的信息需求,然后通过内容架构和写作说明地方式,将这些内容记录下来,便形成了可被复用的模板。

如何使用模板?

使用模板的基本思路基本相同:

  • 理解目标对象;理解信息目标。
  • 理解模板内容架构;理解阐述问题的基本逻辑。
  • 基于模板,结合实际场景和问题,有取舍地写作。

当我们使用模板进行文档开发时,首先,要沉下心来搞清楚,当前信息场景的面向对象和信息目标——这是我们之所以写作文档的根本动机,是为了高效沟通和解决一个非常具体的问题,并不是“为写而写”。

然后,通过模板的内容架构和写作说明,理解阐述问题的逻辑,以及相关人员的信息需求。而且你有没有想过,如果你是一个职场新人,通过模板继承前辈的工作经验,尤其是思考逻辑,这也是非常好的学习过程。

写作时,不要一味地生搬硬套,有的没的都要硬拽上两句,而是要结合自己要阐述的具体问题,有选择地写作相关内容;也不要东拼西凑,差不多的就往里填,而是要注意行文的逻辑延续,前后文的内容自洽。

如此才能真正达成写作一份文档的目的:高效沟通和解决问题。如果费半天劲写出的文档无法满足信息目标,真就只能是:瞎子点灯——白费啦(蜡)。

关于模板前言

有朋友问说,我们就想就事论事,把文档写得简洁明快一些,不想附加太多不必要的内容,所以前言的部分可不可以去掉?

个人并不建议这样做,因为前言部分就像是文档的“元(meta)信息”,是用来介绍文档基本情况的信息,主要包括:

  • 面向对象,包括需要具备的知识和能力;
  • 信息目标,即文档的使用场景和主要内容;
  • 规范约定,包括但不限于常用符号、数字单位的写法和含义;版本号的定义等;
  • 修订记录,即文档历史和主要变更。

前言的作用可大了:

  • 帮助写作者明确文档的场景定位和信息目标,以及了解基本写作规范;
  • 帮助读者了解文档主要内容,阅读文档需要具备的知识和能力,以及文档内容变更等。

其实,前言中很多内容,可以在制作模板时一次性写好,后续写作时,只需要考虑“是否涉及”,判断取舍就可以,并不需要重复写作。

总结

当我们谈“模板”时,你以为我们在谈“文档”吗?不,我们实际关注的是:思维逻辑、知识积累和高效沟通。

今天的分享就是这些内容。希望你可以从此善用模板,通过设计模板积累知识和经验,通过使用模板学习和成长

0 人点赞