清晰的句子
預估時間: 10 分鐘
喜劇作家追求最有趣的效果,恐怖小說作家力求最嚇人的情節,而技術寫作員則以最清晰為目標。在技術寫作中,清晰優先於其他所有規則。本單元將介紹幾種讓句子變得清晰優雅的方法。
選擇強而有力的動詞
許多技術寫作員認為動詞是句子中最重要的部分。選對了動詞,句子的其餘部分就能水到渠成。不幸的是,有些作家只是反覆使用少數幾個溫和的動詞,就像每天用不新鮮的餅乾和軟爛的生菜招待客人。挑選正確的動詞需要多花一點時間,但會產生更令人滿意的結果。
為了吸引讀者並引導他們理解,請選擇精確、有力、具體的動詞。減少使用不精確、弱化、或空泛的動詞,例如:
- be 的各種形式:is、are、am、was、were 等。
- occur (發生)
- happen (發生)
例如,思考一下如何透過強化以下句子中的弱動詞來點燃一個更引人入勝的句子:
弱動詞 | 強動詞 |
---|---|
The exception occurs when dividing by zero. (除以零會發生例外。) | Dividing by zero raises the exception. (除以零會引發例外。) |
This error message happens when... (當...時,這個錯誤訊息會發生。) | The system generates this error message when... (當...時,系統會產生這個錯誤訊息。) |
We are very careful to ensure... (我們是很小心的來確保...) | We carefully ensure... (我們小心地確保...) |
許多作者依賴 be 的各種形式,好像它們是調味架上唯一的香料。不妨在文章裡撒上一些不同的動詞,讓它更可口。話雖如此,be 的形式有時是動詞的最佳選擇,所以也不用覺得必須在寫作時完全避開 be 的每一種形式。
請注意,通用動詞通常表示有其他問題,例如:
- 句子不精確或少了動作者
- 被動語態的句子
練習
請挑選更明確的動詞來釐清下列句子。在此過程中,你可以自由地重新排列句子結構,並加入、修改或刪除詞語:
- When a variable declaration doesn't have a datatype, a compiler error happens.
當變數宣告沒有資料型別,編譯器就會發生錯誤。 - Compiler errors occur when you leave off a semicolon at the end of a statement.
如果陳述句結尾少了分號,編譯器就會發生錯誤。
(1) 幾種可能的答案:
- When a variable declaration doesn't specify a datatype, the compiler generates an error message.
- If you declare a variable but don't specify a datatype, the compiler generates an error message.
(2) 幾種可能的答案:
- Compilers issue errors when you omit a semicolon at the end of a statement.
- A missing semicolon at the end of a statement triggers compiler errors.
減少使用 there is / there are
以 There is 或 There are 開頭的句子,就像是平庸名詞與平庸動詞的結合。這種「平庸的婚禮」會讓讀者感到乏味。用真實的主詞和真實的動詞來向您的讀者表達真愛吧。
在最好的情況下,您可以直接刪除 There is 或 There are(以及句子後面可能的一兩個詞)。例如,思考以下句子:
There is a variable called
met_trick
that stores the current accuracy.
(有一個名為met_trick
的變數,它儲存了當前的準確度。)
移除 There is 會用一個更好的主詞取代通用的主詞。例如,以下任一句子都比原句更清晰:
A variable named
met_trick
stores the current accuracy.
(一個名為met_trick
的變數儲存了當前的準確度。)
The
met_trick
variable stores the current accuracy.
(met_trick
變數儲存了當前的準確度。)
您有時可以透過將真正的動詞和主詞從句尾移到句首來修復 There is 或 There are 的句子。例如,請注意在以下句子中,代名詞 you 出現在句尾附近:
There are two disturbing facts about Perl you should know.
(關於 Perl,有兩個令人不安的事實你應該知道。)
用 you 取代 There are 可以強化句子:
You should know two disturbing facts about Perl.
(你應該知道關於 Perl 的兩個令人不安的事實。)
在其他情況下,作者以 There is 或 There are 開頭,以避免創造真正主詞或動詞的麻煩。如果不存在主詞,請考慮創造一個。例如,以下的 There is 句子沒有指明接收實體:
There is no guarantee that the updates will be received in sequential order.
(無法保證更新將按順序接收。)
用一個有意義的主詞(例如 clients
)取代 There is,可以為讀者創造更清晰的體驗:
Clients might not receive the updates in sequential order。
(客戶可能不會按順序接收到更新。)
練習
請釐清下列句子,移除 There is,必要時也可以重新排列句子、增刪或修改其他詞語:
- There is a lot of overlap between X and Y.
- There is no creator stack for the main thread.
- There is a low-level, TensorFlow, Python interface to load a saved model.
- There is a sharding function named distribute that assigns keys.
- X and Y overlap a lot.
- The main thread does not provide a creator stack.
- TensorFlow provides a low-level Python interface to load a saved model.
- The distribute sharding function assigns keys.
盡量少用某些形容詞和副詞 (選修)
形容詞和副詞在小說和詩歌中表現得非常出色。多虧了形容詞,普通的草地變得「碧草如茵」(prodigal and verdant),了無生氣的頭髮則變成了「閃閃動人、生氣勃勃」(lustrous and exuberant)。副詞讓馬兒「自由狂野地」(madly and freely)奔馳,讓小狗「大聲兇猛地」(loudly and ferociously)吠叫。不幸的是,形容詞和副詞有時也會讓技術讀者抓狂大叫。這是因為形容詞和副詞對技術讀者而言往往過於模糊和主觀。更糟的是,他們會讓技術文件聽起來很像是行銷宣傳。例如,請看以下技術文件中的段落:
Setting this flag makes the application run screamingly fast.
設定此旗標可讓應用程式執行得飛快。
誠然,「飛快」(screamingly fast)能吸引讀者注意,但不見得是好事。對技術讀者而言,應提供事實數據,而非行銷術語。請將模糊的副詞與形容詞重構為具體的數值資訊。例如:
Setting this flag makes the application run 225-250% faster.
設定此旗標可讓應用程式執行速度加快 225-250%。
這樣的修改是否讓句子少了一些魅力?的確有一點,但改寫後的句子有了準確性與可信度。
不要把傳授知識(技術寫作)與宣傳或銷售產品(行銷寫作)混淆。當讀者期待的是學習,就應該提供知識性的內容;不要在教學內容中夾帶宣傳或銷售的資訊。
下一單元:簡短的句子