学习笔记:技术写作原理(四)极简写作与检查文档|青训营;

200 阅读2分钟

科技写作的五步很快就要到底了,现在我来向大家介绍一下极简写作与检查文档,这就是我们科技写作的最后两步。

极简写作

为什么要极简写作?

  1. 减少时间
  2. 易于理解
  3. 节约成本

如何极简写作?

  1. 保持一致:此原则多用于参考型文本。一个名词可以有多种表示方式,在文章中的称呼要统一。比如,接口又被称为API,在文章当中,既然使用了“接口”一词,那就一直在文章中使用这个词汇,不要一会使用“接口”,一会使用“API”,这样会为读者的阅读制造障碍。
  2. 避免啰嗦:此原则多用于概念型文本。在我们阐述一个概念的时候,尽量使用通俗易懂并且简洁明了的语言,不需要添加一些冗长的形容词,或者没有必要的解释。我总结了一个方法,比如,遮住自己认为没有必要的语句,重新读一遍该段落,感受缺失之后是否会对读者的理解产生影响,若是不会产生影响,那么该语句就是属于没有必要的内容,可以删除,以此来使文章更加简洁明了。
  3. 提供路标和索引:此原则多用于操作型文本。在操作过程中,可能会有在操作前需要准备的前置条件,但写在正文里会显得冗长,此时可以提供索引。比如,一篇操作型科技文档阐述了运行go程序的办法,但前提是配置好了vscode的环境并且下载了golang语言。此时我们就可以使用索引提供配置环境的方法,帮助读者使用环境。

检查文档

什么是检查文档?

批判者的视角审视已经写好的内容。

怎么检查文档?

  1. 主题是否明确聚焦,符合读者需求?
  2. 结构是否有逻辑,符合结构化写作原则?
  3. 标题是否符合SPA原则?
  4. 内容是否简单清晰?

这就是技术写作原理五步的全部内容了,欢迎讨论和指正。