Google 技術寫作教程

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

譯文：https://t.co/UDlJUFEDt2?amp=1

翻譯：陳皓(耗子叔)

修訂：伍俊濱

第一部分

語法

詞性

定義

例

Noun

名詞

人，地方，概念或事物

Sam runs races.

山姆賽跑。

Pronoun

代詞

替代另一個名詞的名詞

Sam runs races. He likes to compete.

山姆賽跑。他喜歡競爭。

Adjective

形容詞

修飾名詞的單詞或短語

Sam wears blue shoes

山姆穿藍色的鞋子。

Verb

動詞

一個動作詞或短語

Sam runs races.山姆跑比賽。

Adverb

副詞

修飾動詞，形容詞或其他副詞的單詞或短語

Sam runs slowly.山姆跑得慢。

Preposition

介詞

指定兩個名詞的位置關係的單詞或短語

Sam's sneakers are seldom on his shelf.山姆的運動鞋很少在他的架子上。

Conjunction

連詞

連接兩個名詞或短語的單詞

Sam's trophies and ribbons live only in his imagination.山姆的獎盃和緞帶只存在於他的想象中。

Transition

過渡

連接兩個句子的單詞或短語

Sam runs races weekly. However, he finishes races weakly.

山姆每週參加比賽。但是，他無力完成比賽。

名詞

名詞代表人，地方或事物。朱迪（Judy），南極洲（Antarctica）和 錘子（Hammer）都是名詞，無形的概念（例如健壯性 robustness 和完美性 perfection ）也是如此。例如，我們在下面的示例中加粗了名詞：

In the framework, an object must copy any underlying values that the object wants to change. The protos in the codebase are huge, so copying the protos is unacceptably expensive.

代詞

代詞是一個間接層，它指向或替代了其他名詞或句子。例如：Janet writes great code. She is a senior staff engineer. 示例中，第一句話將Janet建立為名詞。第二句用代詞“ She”代替名詞“Janet”。

在以下示例中，代詞This代替了它前面的整個句子：

Most applications aren't sufficiently tested. This is poor engineering.

動詞

動詞是一個動作詞或短語。當你您想要表示兩個名詞（一個行為者和一個目標）之間的關係時，該動詞就起作用了。動詞標識行為者對目標的作用。每個句子必須至少包含一個動詞。例如，以下每個句子包含一個動詞：

• Sakai prefers pasta. 酒井法子喜歡麵食。
• Rick likes the ocean. 瑞克喜歡大海。
• Smurfs are blue. 藍精靈是藍色的。
• Jess suffers from allergies. 傑西有過敏症。

有些句子會包含多個動詞，如：

• Nala suffers from allergies and sneezes constantly.
  娜娜過敏，經常打噴嚏。
• Chung likes snacks to eat while riding the train.
  Chung喜歡在火車上吃零食。

根據時態和詞綴變化，一個動詞可以包含一個單詞或多個單詞。例如：

• Tina was eating breakfast a few hours ago.
  蒂娜幾小時前正在吃早餐。
• Tina is eating lunch right now.
  蒂娜現在在吃午餐。
• Tina will eat dinner tonight at 7:00.
  蒂娜將在7點吃晚餐。

形容詞和副詞

形容詞修飾名詞。例如，在下面的句子中，注意形容詞如何修飾後面的名詞：

Tom likes red balloons. He prepares delicious food. He fixed eight bugs at work.

大多數副詞修飾動詞。例如，注意下面句子中的副詞是如何(有效地)修飾動詞的：

Jane efficiently fixes bugs.

副詞不一定緊挨著動詞。例如，在下面的句子中，副詞(effective)與動詞(fixes)相距兩個單詞

Jane fixes bugs efficiently.

副詞也可以修飾形容詞或其他副詞。

連詞和過渡

連詞連接句子中的短語或名詞；過渡連接句子本身。最重要的連詞如下：

• and
• but
• or

例如，在下面的句子中，and連接了“code”和“documentation”，而but連接了句子的前半部分和後半部分。

Natasha writes great internal code and documentation but seldom works on open-source projects.

Natasha 編寫了大量的內部代碼和文檔，但是很少在開源項目上工作。

技術寫作中最重要的過度詞如下：

• however
• therefore
• for example

在下面的段落中，請注意過渡如何連接句子並使其上下文相關：

Juan is a wonderful coder. However, he rarely writes sufficient tests. For example, Juan coded a 5,000 line FFT package that contained only a single 10-line unit test.

Juan 是一個出色的程序員。然而，他很少編寫足夠的測試。例如，Juan編碼了一個5000行的FFT包，卻只包含一個10行的單元測試。

單詞

定義新術語或不熟悉的術語

在寫作或編輯時，識別那些目標受眾可能不熟悉的術語。當你您發現此類術語時，請採取以下兩種策略之一：

• 如果該術語已經存在，請鏈接到現有的具體解釋。（不要重新發明輪子）
• 如果你您的文檔中引入了該術語，請定義該術語。如果你您的文檔引入了許多術語，請將定義收集到詞彙表中。

始終使用術語

如果在方法中途更改變量的名稱，則代碼將無法編譯。同樣，如果你您在文檔中間重命名術語，則你您的想法將無法編譯（在用戶頭腦中）。

修養：在整個文檔中始終使用相同的明確詞或術語。一旦你將某個組件命名為thingy之後，不要將其重命名為 thingamabob。例如，以下段落錯誤地將 Protocol Buffers 重命名為 protobufs：

Protocol Buffer 提供了自己的定義語言。…………。這就是 protobufs 贏得如此眾多縣博覽會的原因。

是的，技術寫作是殘酷和充滿限制的，但是至少技術寫作提供了一個很好的解決方法。即，當引入冗長的概念名稱或產品名稱時，你您也可以指定該名稱的縮寫形式。然後，你您可以在整個文檔中使用該簡稱。例如，以下段落很好：

Protocol Buffer（或簡稱 protobuf）提供了自己的定義語言。…… 這就是 protobuf 贏得如此眾多縣博覽會的原因。

正確使用首字母縮寫詞

在文檔或章節中首次使用不熟悉的首字母縮寫詞時，請拼寫完整的術語，然後將首字母縮寫詞放在括號中。拼寫版本和首字母縮寫用黑體字標出。例如：

本文檔適用於遠程觸覺網絡 Telekinetic Tactile Network（TTN）的新手或需要了解如何通過手指運動訂購TTN替換零件的工程師 。

然後可以使用首字母縮略詞，如以下示例所示：

如果不存在緩存條目，則混合器將調用 OttoGroup Server（OGS）來為請求獲取Ottos。OGS是一個存放所有可使用的Otto的存儲庫。OGS以邏輯樹結構組織，具有一個根節點和兩個級別的葉節點。OGS根將請求轉發到葉子並收集響應。

另外，不要在同一文檔中的首字母縮寫詞和擴展版本之間來回切換。

使用首字母縮寫詞還是完整術語？

當然，你您可以正確地引入和使用首字母縮寫詞，但是你您真的要使用首字母縮寫詞嗎？好吧，首字母縮略詞確實減少了句子的大小。例如，TTN 比Telekinetic Tactile Network 短很多。但是，首字母縮略詞實際上只是抽象層。讀者必須在頭腦中將最近學到的首字母縮略詞擴展到整個術語。例如，讀者在腦海中將 TTN 轉換為 Telekinetic Tactile Network，因此“較短”的首字母縮略詞實際上要比整個術語花費更長的時間。

大量使用的首字母縮寫詞基本上會變成另外一個新詞。在出現許多情況後，讀者通常停止將首字母縮略詞展開成具體的單詞。例如，許多Web開發人員已經忘記了HTML這個術語展開後是什麼。

這是首字母縮寫詞的準則：

• 不要定義只會使用幾次的首字母縮寫詞。
• 請定義同時滿足以下兩個條件的首字母縮寫詞：
• 該首字母縮寫詞明顯短於整個術語。
• 該首字母縮寫詞在文檔中很多次出現。

消除代詞歧義

許多代詞指向先前引入的名詞。這種代詞類似於編程中的指針。像編程中的指針一樣，代詞往往會引入錯誤。代詞使用不當會就像程序中的 nullptr 空指針錯誤一樣在讀者的腦海中造成錯誤的認知 。在許多情況下，你您應該簡單地避免代詞，而就直接重複使用該名詞。但是，代詞的效用有時會非常有用。

請考慮以下代詞準則：

• 引入名詞後才使用代詞；在介紹名詞之前，切勿使用代詞。
• 代詞應儘可能靠近指稱名詞。根據經驗，如果將名詞與代詞分隔開的單詞超過五個，請考慮重複使用名詞，而不要使用代詞。
• 如果在名詞和代詞之間引入第二個名詞，請重複使用名詞，而不要使用代詞。

it 和 they

以下代詞在技術文檔中引起最大的混亂：

• it
• they，them 和 their

例如，在下面的句子中，它是指Python還是C ++？

Python是解釋型語言，而C ++是編譯型語言。它具有幾乎類似邪教的追隨者。

再舉一個例子，它們 在接下來的句子中指的是什麼？

將 Frambus 或 Carambola 與 HoobyScooby 或 BoiseFram 一起使用時要小心，因為它們的核心可能會導致意外的大量脫機。

this 和 that

考慮另外兩個問題代詞：

• this
• that

例如，在下面有歧義的句子中，“這” 可能是指Frambus，Foo或兩者：

你您可以使用 Frambus 或 Foo 來計算導數。這 不是最佳的。

使用以下的戰術來消除歧義這個和那個：

• 將 this 或 that 替換為相關的名詞。
• 在 this 或 that 後馬上使用那個名詞。

例如，以下兩個句子中的任何一個都消除了前面的示例的歧義：

Overlapping functionality is not optimal.

This overlapping functionality is not optimal.

主動語態與被動語態

技術寫作中的絕大多數句子都應該是主動語態。本單元教你您如何執行以下操作：

• 區分被動語態和主動語態。
• 將被動語態轉換為主動語態，因為主動語態通常更清晰。

用簡單的句子區分主動語態和被動語態

在主動的語態句子中，主語作用於目標。也就是說，主動語態句子遵循以下公式：

主動語態句=主語+動詞+目標

被動的語態句子則反過來。即，被動語態語句通常遵循以下公式：

被動語態句=目標+動詞+主語

主動語態示例

例如，這是一個簡短而主動語態句子：

The cat sat on the mat. 貓坐在墊子上。

• 主語：The cat
• 動詞：sat
• 目標：the mat

被動語態示例

相比之下，這是被動語態中的同一句話：

The mat was sat on by the cat. 墊子被貓坐著。

• 目標：The mat
• 被動動詞：was sat
• 主語：the cat

一些被動的語態句子省略了主語。例如：

The mat was sat on。

• 主語：不明
• 被動動詞：was sat
• 目標：the mat

誰或什麼坐在墊子上？一隻貓？一隻狗？霸王龍？讀者只能猜測。技術文檔中的好句子可以確定誰對誰做事。

識別被動動詞

被動動詞通常具有以下公式：

passive verb = be 的形式 + 動詞過去分詞

儘管上述公式令人生畏，但實際上非常簡單：

• be 在一個被動動詞中通常是下列詞語之一：
• is / are
• was / were
• past participle verb 過去分詞動詞 通常是一個普通的動詞加上過去式的後綴 ed。例如，以下是過去分詞動詞：
• interpreted
• generated
• formed

不幸的是，某些過去分詞動詞是不規則的；也就是說，過去分詞形式不以後綴ed結尾。例如：

• sat
• known
• frozen

將be和過去分詞的形式放在一起會產生被動動詞，例如：

• was interpreted
• is generated
• was formed
• is frozen

如果短語中包含一個主語，介詞通常會跟在被動動詞之後。(這個介詞通常是幫助你辨別被動語態的關鍵線索)下面的例子結合了被動動詞和介詞：

• was interpreted as 被解釋為
• is generated by 由……生成
• was formed by 由……形成
• is frozen by 被……凍結

祈使動詞通常是主動的

將祈使動詞開頭的句子很容易錯誤地歸為被動。一個祈使動詞是一個命令。編號列表中的許多項目都以祈使動詞開頭。例如，以下列表中的“ Open”和“ Set ”都是祈使動詞：

1. Open the configuration file.
2. Set the Frombus variable to False.

以祈使動詞開頭的句子通常採用主動語態，即使它們沒有明確提及主語。相反，以命令式動詞開頭的句子暗示一個主語。這個隱含的主語就是“你”。

用更復雜的句子區分主動語態和被動語態

許多句子包含多個動詞，其中有些是主動的，有些是被動的。例如，以下句子包含兩個動詞，兩個動詞均為被動語態：

完全轉換為主動語態：

首選主動語態而不是被動語態

大部分時間使用主動態。謹慎使用被動語態。主動語態具有以下優點：

• 大多數讀者會在心理上將被動語態轉換為主動語態。為什麼要使讀者的處理時間更長？通過堅持主動語態，讀者可以跳過預處理階段，直接進入編譯階段。
• 被動語態會使你您的想法模糊不清，使他們的句子變得無聊。被動語態間接報告操作。
• 一些被動語態的句子完全忽略了主語，這迫使讀者猜測主語是誰。
• 主動語態通常比被動語態更短。

Be bold—be active.

閱讀更多 前端時空 的文章

關鍵字: S.H.E 示例 加粗