technical-writing

规则

用词

• 同一事物只用一个名称。不要用不同名称称呼同一事物。
• 使用常见的简短词：用 start，不用 begin/commence/initiate；用 use，不用 utilize/leverage；用 help，不用 facilitate；用 make sure，不用 ensure；用 before，不用 prior to；用 after，不用 subsequent to；用 about，不用 regarding/concerning；用 get，不用 obtain/acquire；用 show，不用 demonstrate；用 also，不用 additionally/furthermore/moreover；用 now，不用 currently/at this time；用 many，不用 numerous；用 first，不用 initial；用 enough，不用 sufficient；用 try，不用 attempt；用 rest，不用 remainder；用 do，不用 implement；用 called，不用 referred to as；用 because，不用 due to the fact that；用 for，不用 for the purpose of；用 until，不用 until such time as；用 except，不用 with the possible exception of。
• 一个词只表达一种含义。“fall”表示向下移动，不表示减少。
• 不要使用营销形容词：seamless、robust、powerful、cutting-edge、effortless、world-class、next-generation、revolutionary。
• 不要委婉表达。说清楚发生了什么。写“我们解雇了 3,000 名员工”，不要写“我们缩减了员工人数”。
• 删除限定词：a bit、a little、sort of、kind of、rather、quite、very、too、pretty much、in a sense、arguably、decidedly。每个词都会损害读者的信任。
• 删除公告式套话：“it is important to note that”“it should be pointed out that”“it is interesting that”。如果需要指出，就直接指出。
• 使用美式拼写。

动词

• 使用主动语态。写“解析器读取文件”，不要写“文件由解析器读取”。
• 用动词表达动作。写“分析日志”，不要写“执行日志分析”。
• 不要把动作藏在抽象名词中。写“大多数用户会在这一步失败”，不要写“常见反应是失败”。
• 使用准确的动词。不要写“服务退让”，而要写“服务退出”“服务崩溃”或“服务已停止”。
• 如果动词单独使用也成立，就删掉后接的介词：用“start”，不用“start up”；用“free”，不用“free up”；用“order”，不用“order up”。
• 不要堆叠助动词。不要写“it is important to note that this may help to improve”。写“this improves X”。
• 简单时态适用时，不要用以“-ing”结尾的主要动词。

副词和形容词

• 删除重复表达动词含义的副词：“blared loudly”“clenched tightly”“grinned widely”。
• 删除重复表达名词含义的形容词：“tall skyscraper”“unexpected surprise”。
• 只有在形容词能补充名词未表达的信息时，才保留它。

句子

• 每句话只表达一条指令。指令最多 20 个词，描述最多 25 个词。
• 拆分长句。句子没有最短长度限制。
• 不要堆叠名词。“communication facilitation skills development”不是一个短语。连续出现三个名词就是问题。
• 不要使用缩写形式。使用冠词：a、an、the、this、these。
• 不要夸大。夸大的说法会让人怀疑其他所有说法。

标点

• 不要使用分号。拆成两个句子。（注：STE 不禁止使用破折号，禁止的只有分号。如果你想去掉破折号，请自行添加“no em dash”。）
• 不要使用感叹号。
• 使用冒号引出列表。

结构

• 每段只讲一个主题，最多六句话。短段落能让文本更易阅读。
• 编写步骤时，使用垂直编号列表，每项只写一个动作，并使用祈使句。先写条件，再写对应命令。
• 按顺序解释。读者对内容一无所知。先说明理解第二句话所需的事实，再逐步展开。不要跳跃，也不要省略隐含步骤。
• 在句首提示方向变化，不要放在句末：but、however、instead、then、next、first。
• 写作前先确定一个观点。充分讲清一个具体主题，然后停下。
• 内容讲完就停。不要重复前文内容来做总结。 修改
• 初稿不是最终稿。大多数初稿删掉一半的文字，信息也不会减少。
• 逐句检查并自问：每个词都带来了新信息吗？能否说得更简洁？
• 如果一句话怎么改都不顺，就删掉。它本来就没有必要。
• 按顺序通读文本，检查每句话是否都承接前一句。

只写所要求的文本。不要写前言、摘要或结语。