開發人員的技術寫作

HTML、CSS、JavaScript、Python、PHP、C++、Dart--有這麼多的程式語言，你甚至可能完全精通其中的幾種。但是，隨著我們的目標是寫出更多、更好的程式碼，我們用日常語言寫作和交流的方式變得越來越重要......甚至可能被忽略了。

我們編寫和討論程式碼的方式可以說與程式碼本身同樣重要。儘管你可能在這個問題上持不同觀點，但我們都可以同意，我們的言辭既會提高程式碼的有效性，也會損害程式碼的有效性。

在這篇文章中，我想概述一下這兩個看似截然不同的領域--程式設計和寫作--如何能夠結合起來，將我們的開發技能提升到一個新的水平。

等等，技術寫作？是的你沒看錯。我真的相信我們在某種意義上都是作家。我會在這裡給你介紹寫作技巧、建議以及例子，使你成為更好的開發者和溝通者。

本文包括以下部分：

• 技術寫作無處不在
• 什麼才是好語法？
• 編寫程式碼註釋
• 編寫pull request
• 報告bug
• 與客戶溝通
• 編寫微文案
• 編寫無障礙標記
• 總結

技術寫作無處不在

2021年，流行的Mac Git使用者端Tower背後的團隊對4000多名開發者進行了調查，發現他們中近50%的人每天花3-6個小時來編寫程式碼。

是的，這是一個針對特定小眾群體的調查，但我想我們中的很多人都在這個範圍內。無論如何，開發者並非7 * 24都在編寫程式碼，因為正如這個調查所顯示的，我們花了很多時間在做其他事情。

這可能包括以下事情：

• 演示一個新功能，
• 記錄這個新功能，
• 更新與這個新功能相關的工作計劃，或者
• 將支援這個新功能的工作積壓。

當然，總是有時間上廁所和玩Wordle遊戲的。

無論如何，我們通常所做的大部分事情都涉及與團隊、同事、客戶、使用者以及其他開發者等人溝通。

所以我們確實花了很多時間通過文字與人類交流，除了通過程式碼與計算機交流之外。文字是書面語言。如果我們能更好地書寫文字，我們就能更好地交流。當我們更好地交流時，我們就更有可能得到我們想要的。

而且這還不是全部。一些程式設計師還喜歡製作他們自己的產品，這意味著他們需要將市場行銷作為工作的一部分。技術寫作在這方面也起著重要作用。所以沒錯，我可以非常公正地說，技術寫作確實無處不在。

什麼才是好語法？

有這麼多的程式語言，我們最不想做的就是學習另一種語言。

語法是英語的一個重要組成部分，它釋放了溝通的全部潛力。它使我們更加正式、專業和連貫。

讓我給你簡要介紹一下語言。

英語語法

正如程式語言，英語有一個明確的語法，它從單詞開始。

單詞是英語的組成部分，它們可分為八個類別：

• 名詞（Nouns）。這些可以是人名、動物、地點、概念和物體的名稱。

  • CSS 是前端開發的核心語言之一。

• 動詞（Verbs）。動詞傳達動作。即使「is」也可以被視為一種動作。

  • 瑪西婭早上編寫程式碼，下午回覆電子郵件。

• 形容詞（Adjectives）。形容詞是我們描述名詞的方式。它們就像後設資料，為句子增添更多細節，描繪出生動的畫面。

  • CSS是一種優雅而富有詩意的語言。
  • HTML表格是複雜而繁瑣的。
  • 盒模型對於理解CSS很重要。

• 介詞（Prepositions）。介詞在名詞和其他單詞之間建立關係，通常表示方向、時間、地點和空間。

  • 你將你的工作提交到倉庫了嗎？
  • 對於這個元件，最好的方法是什麼？
  • 我們與真實使用者進行了訪談。

• 副詞（Adverbs）。有時候需要更具體的動作描述，因此我們使用副詞，比如「跑得快」和「編譯慢」。它們通常以「-ly」結尾。

  • 這絕對是所有想法中最好的。
  • 奇普耐心地等待戴爾的反饋。
  • 團隊在專案上勤奮地工作。

• 連詞（Conjunctions）。連詞連線句子中的短語。

  • CSS用於樣式設計，而HTML用於標記。
  • 是的，我編寫程式碼，但我也從事設計工作。
  • 那修復了這個漏洞。然而它又引入了一個新的漏洞。

• 過渡詞（Transitions）。段落由相互連線的句子組成，這些句子使用過渡詞來連線。

  • 有很多程式語言。然而，只有少數被應用於網路行業。
  • 首先，克隆該目錄。
  • 我喜歡這種方法，但另一方面，我也知道另一種方法。

• 代詞（Pronouns）。當名詞重複出現時，我們會用代詞來代替，比如「他」，「它」和「那個」。

  • CSS是一種樣式表語言。我們使用它來為網站新增樣式。
  • 託尼熱愛編碼，他每天練習。
  • 我們的客戶精通技術，因為他們瞭解程式碼。

將這些語言元素看作UI元件：它們是模組化的部分，你可以移動它們以構建完整而健壯的句子，就像你可能會組裝完整而健壯的UI一樣。所有元件是否始終需要存在？當然不需要！使用所需的部分組裝句子，就像你使用介面一樣來完成體驗。

語氣和語調

詞彙、標點符號、句子結構和單詞選擇。這些都是英語的組成要素。我們用它們來分享想法，與朋友和家人交流，並給同事傳送電子郵件。

但考慮我們資訊的聲音是至關重要的。一個感嘆號就能完全改變資訊的語氣，這很神奇：

1. 我喜歡程式設計。
2. 我喜歡程式設計！