选择合适、正确的用词有助于提升篇章的可读性。
使用对开发者友好的词语
l 使用第二人称
通常,在文档中使用第二人称(you)来指代开发者。
− 如果您要告诉开发者应该做某事,可以使用祈使句(暗含you主语)。
− 通常最好避免使用we, our或us。
l 使用缩略词
使用常见的缩略词,例如it's, you're, that's, and don't这样友好的非正式的语调。
− 避免出现模棱两可或非常奇怪的缩略词,例如there'd, it'l, and they'd。
− 请勿在UI文本中混合使用缩略词及其等效拼写形式。例如,不要在同一UI中使用can't 和 cannot。
− 切勿由名词和动词构成缩略语,例如ABC's developing a lot of new cloud services.
使用简单而准确词语
使用简单、含义精确的词语,删除没有实质内容的词语。
l 使用强意主动动词(strong active verb)是英文表达清晰、简练的关键。尽可能避免弱动词或含糊的动词,如be、have、make和do。
示例:
使用 | 而非 |
use | utilize, make use of |
remove | extract, take away, eliminate |
tell | inform, let know |
l 当一个词就足够时,不要使用两个或三个词。
示例:
使用 | 而非 |
to | in order to, as a means to |
also | in addition |
connect | establish connectivity |
l 尽可能选择含义明确的词语。
示例:
使用 | 而非 |
Because | Since |
l 省略描述如何、何时或何地这样不必要的副词。除非它们对陈述的意义非常重要,否则就不要提及。
示例:
quite, very, quickly, easily, effectively
l 如果使用既可以是名词又可以是动词的单词,例如:file, post, mark, screen, record, 和report等,需要依赖句子结构和上下文来消除歧义。
谨慎使用术语
术语类型多种多样,有的是日常的词被赋予了新的含义,比如cloud, batch, 或dashboard。有的常用词被组合成术语,比如telemedicine或email。当术语是传达信息最清晰的方式时,可以谨慎使用它们。
尽可能使用常用词
当一个日常术语可以实现目的的时候,不要使用技术术语。例如,不要使用rip来指从CD中复制文件,如果可以使用请copy代替。
不要认为每个人都能理解技术术语
当必须使用术语进行准确交流时,请在上下文中定义它们。
术语全局保持一致
当决定使用一个术语时,请在产品和服务、工具、网站和营销传播中保持一致使用该术语。目标是保持只有一个术语、一个概念。
如果已经存在该术语,则不要创建新术语
如果现有术语符合您的目的,请不要创建新的术语。如果必须创建一个新术语,请验证它是否被用于表示其他含义。
正确使用缩略语和缩写词
l 首次使用缩略语或缩写词时,提供全称。
l 标题中可以包含首次出现的缩略语,不需要加括号给出全名,但需要在紧接的正文中给出全名或解释。
l item list和表格中第一次出现缩略语时,直接在item list或表格中给出缩略语的全称。
l 缩略语和其它成分构成一个整体时,可在后文进行解释。
示例:This chapter describes the basic features of the infoX-SMS system. SMS is short for….
l 如果缩略语在文中第一次出现时为复数形式,括号中的缩略语要加“s”;第二次出现为单数或者复数形式时都不必给出全称。
示例:The internal and external networks belong to different virtual local area networks (VLANs).
l 尽量不使用不规范或一词多义的缩略语。
人们对于缩略语的了解不尽相同,一个缩略语往往对应多个术语,所以通常情况下,过多地使用缩略语会使人产生误解。
反例:
TS: timeslot
WS: workstation
l 单位缩略语的大小写遵循国际惯例。
示例:dB、kg
l 缩略语末包含点且出现在句末时,仅保留一个点。
示例:Sun Cluster is a product developed by Sun Microsystems Inc.
l 根据缩略语或缩写词发音使用冠词a或an。
若缩略语或缩写词习惯上按照单词拼读,则根据单词发音选择使用a或an;若缩略语或缩写词习惯上按照字母分开读,则根据首字母发音选择使用a或an。
示例:
an MS
an UP action
a URL
l 不使用缩略语作动词。
反例:
FTP the file to the network manager.
l 尽量避免在缩略语的全称中还包含其他缩略语。这种嵌套的缩略语通常很难让全球的读者理解。在许多国家,缩略语都要求至少要完全拼写出一次。
但有些情况下,如果全部展开会造成修饰词堆砌的现象,也会给读者造成理解困难。例如,LDIF是指LDAP data interchange format。如果全部展开为lightweight directory access protocol data interchange format,会造成多个名词堆砌。这种情况下,可以进行适当调整。
− 如果前文已经对LDAP进行了解释,LDIF的全称可以直接使用LDAP data interchange format.
− 如果尚未提及LDAP的全称,添加单独的说明给出LDAP的全称。比如…LDAP data interchange format (LDIF). LDAP refers to ….
l 带+号的缩略语需要根据标准或者业界使用习惯给全称。
示例:
Session Initiation Protocol Plus (SIP+)
避免对常见词汇进行创新
大多数人都知道词的普遍定义——通常在字典中出现的第一个词。请使用大家最熟悉的词。如果不合适,则用对应的常用词来定义新术语。
l 不要从一个现有词中创建一个新词。
示例:
不要用bucketize表达group的含义。
l 不要对一个普通的词添加新的含义。
示例:
不要用graveyard表达archive的含义。
l 谨慎使用行业专用的常用词。如果必须使用行业的特定定义,请在上下文中对该词进行定义。
例外:当特定行业词语,如hacker,发展为大众熟知的表达。
当存在疑问时,使用一个简单且有明确含义的词依然是我们的首要选择。
l 不要使用动词作为名词或使用名词作为动词。
示例:
使用 | 而非 |
open an invitation | open an invite |
affect performance | impact performance |
download the paper | get the download |
respond to the request | respond to the ask |
避免冒犯性或敏感词汇
请谨慎使用如下表所示类别词汇。不当使用将影响开发者体验及品牌形象,甚至可能会引入法律风险。
类别 | 子类 | 说明 |
Vulgar | Profane | Profane: Profanities are offensive words used in a way that shows you do not respect God or holy things. |
Swearing and cursing | ||
Insulting | ||
Political | Politics | Political satire: Controversial issues surrounding the current world and country situation |
Societal | Civil rights | Terms specific to race and ethnicity, religion, privacy, gender, age, sexual preference, titles, and health and abilities. |
Unlawful act | Hate speech: Terms that include hate speech inciting racism, sexism, homophobia, or other forms of bigotry Drug use Terms seen as promoting illegal drug use Gambling: Terms associated with gambling activity or its promotion |