Technical Writing: English Grammar Rules for Technical Documents: 20 Dos and Don’ts

這是 Claude 翻譯的 English Grammar Rules for Technical Documents: 20 Dos and Don'ts，會寫這篇文章是因為 Hugo 文檔實在是太爛了因此才有動機研究「怎麼寫好文檔」。

以下開始翻譯。

hireawriter.us

撰寫清晰簡潔的技術文件需要遵循正確的文法規則，這有助於避免誤解並確保專業性。技術寫作與其他寫作風格不同，因為精確度至關重要，即使是微小的文法錯誤也可能導致混淆。以下是技術文件撰寫時應遵守與避免的 20 項核心文法原則。

1. 應：使用主動語態

  • 應：「系統即時處理資料。」
  • 不應：「資料由系統即時處理。」

說明： 主動語態讓句子更直接、更容易理解，而被動語態可能顯得模糊或繁複。

2. 應：術語保持一致

  • 應：「點選『提交』按鈕。」
  • 不應：「按下『提交』鍵，然後點選按鈕以完成提交。」

說明： 對於相同的動作或物件，全文應使用一致的術語來描述。不一致會造成混淆。

3. 應：使用平行結構

  • 應：「使用者可以輸入資料、處理檔案並產生報告。」
  • 不應：「使用者可以輸入資料、處理檔案，以及報告的產生。」

說明： 平行結構能維持句子結構的平衡，使指示更清晰易讀。

4. 應：具體明確

  • 應：「變更設定後請重新啟動應用程式。」
  • 不應：「進行變更，然後重新啟動。」

說明： 明確指出使用者需要做的具體事項，以避免模糊不清。

5. 應：使用牛津逗號以求清晰

  • 應：「報告包含銷售、營收和支出的資料。」
  • 不應：「報告包含銷售、營收和支出的資料。」（原文未加牛津逗號）

說明： 牛津逗號能確保清晰度，這在講求精確的技術寫作中尤為重要。

6. 應：使用簡單清楚的語言

  • 應：「從下拉選單中選擇該選項。」
  • 不應：「從前述之下拉列表中選出所欲之項目。」

說明： 使用簡單直白的語言，確保盡可能多的讀者都能理解文件內容。

7. 應：避免使用口語或俚語

  • 應：「按下電源鈕以啟動裝置。」
  • 不應：「按一下電源鈕讓它跑起來。」

說明： 技術文件必須保持專業與清晰，避免使用可能被誤解的非正式語言。

8. 應：使用一致的度量單位

  • 應：「該包裹重 1.5 公斤。」
  • 不應：「該包裹在本節重 1.5 公斤，在其他地方則寫作 1500 公克。」

說明： 使用一致的度量單位可避免錯誤與混淆，在技術領域中尤其重要。

9. 應：避免雙重否定

  • 應：「系統允許使用者檢視報告。」
  • 不應：「系統並非阻止使用者無法檢視報告。」

說明： 雙重否定會使讀者困惑並模糊原本的意思。

10. 應：一般性陳述使用現在式

  • 應：「軟體需要更新才能正常運作。」
  • 不應：「軟體當時需要更新才能正常運作。」

說明： 現在式能讓文字更即時、更貼切，尤其適用於操作指示或一般性陳述。

11. 應：謹慎使用代名詞

  • 應：「點選圖示以開啟檔案。」
  • 不應：「點它以開啟它。」

說明：「它」這類代名詞在技術文件中可能造成不清楚的情況。當有混淆的可能時，應始終明確指出主詞。

12. 應：確保主詞與動詞一致

  • 應：「資料由程式分析。」
  • 不應：（主詞動詞數量不一致的例子）

說明： 確保主詞與動詞在數量（單數/複數）上一致。在技術寫作中，準確性至關重要。

13. 應：避免冗贅

  • 應：「裝置連接到網路。」
  • 不應：「裝置連接到網路連線。」

說明： 冗贅的措辭只會拉長文字卻不增加價值。應保持簡潔。

14. 應：使用項目符號或編號列表

  • 應：
    • 步驟一：開啟應用程式。
      • 步驟二：輸入您的憑證。
      • 步驟三：點選「提交」。
  • 不應：「首先，開啟應用程式。接著，您應該輸入您的憑證。最後，點選提交。」

說明： 列表有助於分解複雜的指示，並提升可讀性。

15. 應：避免修飾語錯置

  • 應：「執行程式之後，系統會關機。」
  • 不應：「系統在執行程式之後關機。」（語序易生歧義）

說明： 確保修飾語緊鄰其所修飾的詞語，這在操作指示中尤其重要。

16. 應：正確使用冠詞

  • 應：「使用者可以透過點選『註冊』按鈕來建立帳號。」
  • 不應：「使用者可透過點選『註冊』按鈕建立帳號。」（缺少冠詞）

說明： 遺漏冠詞（如英文中的 a、an、the）會讓文字顯得不完整或不清楚。

17. 應：謹慎使用縮寫與縮略字

  • 應：「使用應用程式介面（API）來擷取資料。」
  • 不應：「未事先說明就直接使用 API 來擷取資料。」

說明： 縮寫與縮略字在首次出現時應加以定義，以確保讀者理解。

18. 應：避免過長的句子

  • 應：「首先，選擇選單。然後選擇您的設定。」
  • 不應：「選擇選單，然後接著，導覽到您的設定，這可以在偏好設定分頁中找到，以調整應用程式來符合您的需求。」

說明： 較短的句子更容易理解，尤其是在操作指示或技術文件中。

19. 應：使用正確的標點符號

  • 應：「點選『開始』，程式將會初始化。」
  • 不應：「點選『開始』程式將會初始化。」（缺少逗號）

說明： 正確使用逗號及其他標點符號，以避免句子沾黏並提升可讀性。

20. 應：使用正式語氣

  • 應：「系統將於凌晨 3 點自動更新。」
  • 不應：「系統要在凌晨 3 點更新了喔。」

說明： 技術寫作應維持正式語氣，避免使用非正式或口語化的措辭。

技術寫作者的文法規則

遵循這些文法上應做與不應做的原則，能提升技術文件的清晰度、可讀性與專業性。無論您撰寫的是操作手冊、使用指南，或技術行銷材料，應用這些規則都能確保讀者無誤地理解您的指示與重要訊息。清晰的溝通在技術寫作中至關重要，而文法在達成此目標上扮演著關鍵角色。

原文

hireawriter.us

Writing clear and concise technical documents requires adherence to proper grammar rules, which help avoid misunderstandings and ensure professionalism. Technical writing differs from other writing styles because precision is critical, and even minor grammatical mistakes can lead to confusion. Below are 20 essential grammar dos and don’ts for technical documentation.

1. Do: Use Active Voice

  • Do: "The system processes data in real-time."
  • Don’t: "Data is processed by the system in real-time."

Explanation: Active voice makes sentences more direct and easier to understand, while passive voice can sound vague or convoluted.

2. Do: Be Consistent with Terminology

  • Do: "Click the ‘Submit’ button."
  • Don’t: "Press the ‘Submit’ key and then click the button to submit."

Explanation: Stick to consistent terms to describe the same actions or objects throughout the document. Inconsistency leads to confusion.

3. Do: Use Parallel Structure

  • Do: "The user can input data, process files, and generate reports."
  • Don’t: "The user can input data, processes files, and report generation."

Explanation: Parallel structure maintains balance in sentence construction, making instructions clearer and more readable.

4. Do: Be Specific

  • Do: "Restart the application after changing the settings."
  • Don’t: "Make changes, then restart."

Explanation: Avoid ambiguity by specifying exactly what the user needs to do.

5. Do: Use the Oxford Comma for Clarity

  • Do: "The report includes data on sales, revenue, and expenses."
  • Don’t: "The report includes data on sales, revenue and expenses."

Explanation: The Oxford comma ensures clarity, especially in technical writing where precision is paramount.

6. Do: Use Simple and Clear Language

  • Do: "Select the option from the dropdown menu."
  • Don’t: "Elect to make a selection from the aforementioned dropdown list."

Explanation: Use simple, straightforward language to ensure the widest possible audience can understand the document.

7. Do: Avoid Colloquialisms or Slang

  • Do: "Press the power button to start the device."
  • Don’t: "Hit the power button to fire it up."

Explanation: Technical documents must remain professional and clear, avoiding informal language that may be misunderstood.

8. Do: Use Consistent Units of Measurement

  • Do: "The package weighs 1.5 kilograms."
  • Don’t: "The package weighs 1.5 kg in this section, and 1500 grams elsewhere."

Explanation: Using consistent units of measurement prevents errors and confusion, particularly in technical fields.

9. Do: Avoid Double Negatives

  • Do: "The system allows the user to view the report."
  • Don’t: "The system doesn’t prevent the user from not viewing the report."

Explanation: Double negatives can confuse the reader and obscure the intended meaning.

10. Do: Use Present Tense for General Statements

  • Do: "The software requires an update to function properly."
  • Don’t: "The software required an update to function properly."

Explanation: Present tense makes the writing more immediate and relevant, especially for instructions or general statements.

11. Do: Use Pronouns Carefully

  • Do: "Click the icon to open the file."
  • Don’t: "Click it to open it."

Explanation: Pronouns like "it" can be unclear in technical documentation. Always specify the subject when there’s room for confusion.

12. Do: Ensure Subject-Verb Agreement

  • Do: "The data is analyzed by the program."
  • Don’t: "The data are analyzed by the program."

Explanation: Ensure that the subject and verb agree in number (singular/plural). In technical writing, accuracy is essential.

13. Do: Avoid Redundancy

  • Do: "The device connects to the network."
  • Don’t: "The device connects to the network connection."

Explanation: Redundant phrases can make your writing longer without adding value. Keep it concise.

14. Do: Use Bullets or Numbers for Lists

  • Do:
    • Step 1: Open the application.
      • Step 2: Enter your credentials.
      • Step 3: Click ‘Submit’.
  • Don’t: "First, open the application. Next, you should enter your credentials. Finally, click submit."

Explanation: Lists help break down complex instructions and improve readability.

15. Do: Avoid Misplaced Modifiers

  • Do: "After running the program, the system shuts down."
  • Don’t: "The system shuts down after running the program."

Explanation: Make sure modifiers are placed next to the word they are modifying, especially in instructions.

16. Do: Use Definite and Indefinite Articles Correctly

  • Do: "A user can create an account by clicking the ‘Sign Up’ button."
  • Don’t: "User can create account by clicking ‘Sign Up’ button."

Explanation: Missing articles ("a," "an," "the") can make your writing feel incomplete or unclear.

17. Do: Be Cautious with Abbreviations and Acronyms

  • Do: "Use the application programming interface (API) to retrieve data."
  • Don’t: "Use the API to retrieve data without prior explanation."

Explanation: Always define abbreviations and acronyms on first use to ensure the reader understands.

18. Do: Avoid Overly Long Sentences

  • Do: "First, select the menu. Then choose your settings."
  • Don’t: "Select the menu, and then after that, navigate to your settings, which can be found under the preferences tab, to adjust the application to suit your needs."

Explanation: Shorter sentences are easier to follow, particularly in instructional or technical documents.

19. Do: Use Accurate Punctuation

  • Do: "Click ‘Start,’ and the program will initialize."
  • Don’t: "Click ‘Start’ and the program will initialize."

Explanation: Use commas and other punctuation correctly to avoid run-on sentences and improve readability.

20. Do: Use Formal Tone

  • Do: "The system will automatically update at 3 a.m."
  • Don’t: "The system’s gonna update at 3 a.m."

Explanation: Maintain a formal tone in technical writing, avoiding informal or conversational phrases.

Grammar Rules for Technical Writers

Adhering to these grammar dos and don’ts will enhance the clarity, readability, and professionalism of your technical documents. Whether you're writing manuals, user guides, or technical marketing materials, applying these rules will ensure your readers understand your instructions and key messages without confusion. Clear communication is essential in technical writing, and grammar plays a crucial role in achieving that.

#文檔撰寫 #筆記