谷歌技术文档写作课程笔记 2 用词

Posted by Shiwei Shang on June 20, 2025

技术文档写作中的用词

对于技术文档中用词的问题,主要有以下几个方面值得我们特别注意。

陌生的术语要解释

提到新词或者术语的时候,一般有两种处理方式:

  • 给这个词加一个链接,跳转到已有的解释。
  • 在这个词后边紧跟解释,如果文档术语特别多,直接建一个话题,用来解释整个文档中出现的所有新词或术语。

术语的使用要统一

和日常写作不同,技术文档的术语要前后统一,不可以前面用一个词,后面用另外一个同义词。

缩写的使用要合理

第一次使用缩写的时候要先把全称写出来,把缩写放在全称后面的括号里。如果缩写的次数出现得比较少,最好直接都使用全称。有时候,缩写反而减缓读者的理解,因为读者需要一些时间在头脑中还原它的全称。所以:

  • 缩写能大大缩短全称的时候用缩写。
  • 缩写在文本中需要多次出现的时候用缩写。
  • 缩写用得次数少的情况下直接用全称。

代词的指代要清晰

在短句中,我们能很容易地理解代词到底指代的是哪个人、哪件事、哪个东西。但是在复杂的句子中,代词容易让我们感到困扰。有的时候我们很难判断代词到底指代的是离它比较近的那个词还是离它比较远的那个。因此,在复杂的句子中要谨慎使用代词,要么把代词替换成具体的词,要么把复杂的句子变成简短的句子。