Clear sentences

喜剧作家追求最有趣的结果，恐怖作家追求最惊悚的，技术文档作者则追求最清晰的。在技术文档写作中，清晰是优先于其他所有准则。本单元建议了使句子优美清晰的一些方法。

选择强动词

许多技术文档作者认为动词是句子中最重要的部分。选择正确的动词，句子剩下的部分将不言自明。不幸的是，一些作者只重复使用一些平淡的动词，就像每天只给客人不新鲜的的苏打饼和湿漉漉的生菜一样。选择正确的动词需要花费更多时间，但会产生更令人满意的结果。

为了吸引和启发读者，选择精确、有力、具体的动词。减少使用不精准、弱的或通用的动词，例如：

• be动词的各种形式： is, are, am, was, were等
• occur
• happen

参考下面例句中如何使用强动词让句子变得更“燃“：

许多作者对be动词有强依赖，好像这是餐架上唯一的香料一样。选择各种不同的动词，让你的文档更加“开胃”。 当然，be动词有时是最佳选择，所以不要认为你要从你的文章中拿掉每个be动词。

请注意，通用动词往往暗示着其他的小毛病，例如：

• 句子中的主语是不精确的，或缺失的。
• 被动语句。

练习

选择精准的动词让句子意义变得更明确。你可以随意重排句子并添加、修改或删除单词：

1. When a variable declaration doesn't have a datatype, a compiler error happens.
2. Compiler errors occur when you leave off a semicolon at the end of a statement.

去掉 there is/there are

使用 there is或there are的句子就像通用名词嫁给了通用动词。普通的婚礼让观众乏味。给读者真诚的“爱”，使用真正的主语和真实的动词吧。

最佳状况下，你只需简单删掉句子里的There is或There are（或许句子后再删除一两个其他词）即可。参考如下例句：

There is a variable called met_trick that stores the current accuracy.

去掉There is，把真正的主语呈现出来。例如，以下任何一个句子都比原文更清晰：

A variable named met_trick stores the current accuracy.

The met_trick variable stores the current accuracy.

有时，你可以把真正的主语和动词从句末移动到句首来修复There be句子。例如，下面句子中代词you出现在句末：

There are two disturbing facts about Perl you should know.

把There is替换成You是句子更佳明确。

You should know two disturbing facts about Perl.

其他情况下，作者是为了避免创建真正的主语和动词的麻烦，而使用了There is或There are。如果没有主语，那么就创建主语。例如，下面的There is语句没有标明接收实体：

There is no guarantee that the updates will be received in sequential order.

通过将There is修改为更有意义的主语（例如clients），为读者创建更清晰的体验：

Clients might not receive the updates in sequential order.

练习

通过去掉There is，让句意更加明确（你可以随意重排句子并增加、修改或删除单词）:

1. There is a lot of overlap between X and Y.
2. There is no creator stack for the main thread.
3. There is a low-level, TensorFlow, Python interface to load a saved model.
4. There is a sharding function named distribute that assigns keys.

减少某些形容词和副词的使用（Optional）

形容词和副词在小说和诗歌中大放异彩。

Thanks to adjectives, plain old grass becomes prodigal and verdant, while lifeless hair transforms into something lustrous and exuberant. Adverbs push horses to run madly and freely and dogs to bark loudly and ferociously.Unfortunately, adjectives and adverbs sometimes make technical readers bark loudly and ferociously.

[!Note]

译注，为保证不破坏原意，上段并未翻译。

这是因为对技术文档的读者来讲，形容词和副词往往过于松散且主观。更为甚者，形容词和副词让技术文档听起来像营销材料一样危险。例：

Setting this flag makes the application run screamingly fast.

诚然, " screamingly fast"能引起读者的注意，但并不是从好的一面。请给你的读者提供真实的数据而不是营销言论。你需要将没有确定性的形容词和副词修改为客观的数字信息。例如：

Setting this flag makes the application run 225-250% faster.

这个修改是否剥夺了这句话的一些魅力？没错，是有一些，但是修改后的句子变得更准确和可信。

Reference

原文：https://developers.google.com/tech-writing/one/clear-sentences