如何撰寫英文技術文件 - iThome

如果有寫作中文技術文件的習慣，應該會有幫助，這表示開發者在表達一件事物的能力具有基礎。

如果沒有，我想也沒有關係，找一篇感興趣的英文文件，不用太長 ... 移至主內容 文/林信良 | 2017-04-30發表 現今想要跟上這世界不斷變遷、演進的技術，除了不得不的英文閱讀能力之外，談到要將自己的想法表達出來，對不少開發者來說，英文就像是揮之不去的夢魘了。

若不想要老是遇到用英文表達的場合就尷尬，那就想辦法改變吧！腦袋跟不上嘴巴的話，那就先從使用英文撰寫技術文件的表達開始。

借鏡程式語言 談英文寫作的書很多，談技術英文寫作的書也不在少數，也許你也試過幾次，然而總不見成效？ 暫且把英文寫作擺一邊，談談如何用程式語言來表達想法，相信這是開發者再熟悉不過的過程了！ 通常是從文件或者書籍上，認識語言的基本元素、語法，乃至於風格典範，然而，文件看再多看得再懂，沒有實際動手撰寫，就什麼也不是。

因為，一開始通常是很笨拙的，開發者會需要一些範例，瞭解相關元素、語法如何運用，也許試著拿另一門語言的範例進行翻譯來做為練習。

雖然沒有受過專業的英文寫作訓練，然而，為了克服自己在英文表達上的弱點，多年前我就是這麼想的，英文既然也是一門語言，身為開發者，哪有搞不定英文的道理，既然在學習各種程式語言時，都經歷過以上類似的過程，試著拿來套用在英文寫作上，會是如何？ 首先我採取的方式是，重新熟悉英文寫作時一些基本元素，就像程式語言入門一樣，只要先掌握語言元素某個最小子集，就能開始練習，因此這樣的書不用太多本，也不建議太厚，重點也是找本看得懂的就可以了，開發者多半接觸過不少英文技術文件，此時的重點只是將基本的英文寫作元素，與那些技術文件建立初步的連結。

如果有寫作中文技術文件的習慣，應該會有幫助，這表示開發者在表達一件事物的能力具有基礎。

如果沒有，我想也沒有關係，找一篇感興趣的英文文件，不用太長，先試著將它翻成中文，目的是在於理解文件內容，以及在翻譯過程中，認識到語言之間並不是一對一的關係。

無論是程式語言之間，或者是中文與英文之間都一樣，沒有人想看到英式中文，因此，你應該也不會想寫出中式英文。

然後，試著針對相同主題自行寫篇文件，一下子要用英文寫作還是有困難的，先試著用中文寫出來，然後將中文翻譯成英文，在這個過程中，某個概念也許不清楚如何以英文表達，此時，可以回頭參考先前的英文文件，如果覺得其中某句可以直接複製過來也沒關係，這就跟學習一門程式語言，一開始也是照抄範例的情況，是一樣的。

在每個角落練習 為什麼要用英文撰寫技術文件？每個人也許會因為不同的場景，而觸發不同的動機，至於我，也許有些人注意到了，近幾年在一些研討會上使用的投影片，內容上都會使用英文，回想最初的原因之一，主要是在於老聽見的一句話：「臺灣市場太小」，既然如此，「那就想辦法讓世界看到」是我後來的想法。

程式語言接觸越久就越熟悉，一開始也不用雄心壯志想寫個什麼大軟體，從小程式開始。

憑著這樣的想法，只需要簡短句子、綱要的投影片，自然就是個好的英文練習對象，而回饋也是顯而易見的。

像是PyConTaiwan2013、2014RubyConfTaiwan等研討會投影片，都曾收到來自國外開發者的回饋，特別是2014RubyConfTaiwan中提到的Typechecking，在Twitter上，引起國外開發者一陣子的討論時，我想到就非常地開心。

如果真的沒有練習的對象，那麼，就從自己的程式碼註解下手吧！可以一邊寫註解，一邊檢視程式碼，又一邊練習英文，這是一舉多得的做法（也許比較適合用在自己的寵物專案）。

另一個方式是找個程式庫，儘管它已經有API文件了，也還是試著為上面的模組、類別或函式寫註解，這一方面可以學習如何撰寫API文件，另一方面，類似地，某個概念無法用英文寫出來時，就看看人家API文件上是怎麼表達的。

如果過去曾經有撰寫技術文件的習慣，找幾篇自己得意的文件，試著將它們翻成英文。

如果曾經撰寫過一系列的文件，並想要試著全部翻譯，也會是個不錯的挑戰，例如iThome鐵人賽的系列文章。

想想看，如果除了懂中文的人之外，來自世界各地的人們也能看懂你的系列文件，這會是多棒的一件事。

當然，我們畢竟不是身處在以英文為母語的國家，因此，我們需要參考，瞭解自己是不是適切地表達了想法。

如果過去看過不少英文技術文件，這時可以派上用場，試著看看文件或書中的表達方式；就像是維基百科上的條目，都有英文，試著將自己想表達的概念關鍵字英文，放到網路搜尋，看看有沒有直接相關的例句（stackoverflow往往派上用場），這些都是不錯的參考對象。

與國外社群互動 在撰寫技術文件時，首要重點是搞清楚正確的對象，如果撰寫的是英文技術文件，重點也在於認清，文件的對象應該是不懂中文，而你想要透過英文向他傳達想法的人。

因此，將你的英文文件放到中文社群中，其實沒有太大的意義，想請中文社群中的讀者指正英文是否有錯誤，有時可能會有反效果（應該看過吧！英文正確與否，有時會是個吵架的話題）。

找個國外社群切入，試著回答問題、參與其中的討論，或者是發表作品，會是個更實際的作法，因為他們只能透過你發表的英文，來理解想傳達的概念，而在互動的過程中，就可以逐漸修正自己的表達方式，像是從對方的回應中，看到某個更為適用的字眼、句型或者是相關參考鏈結。

在GitHub、Thingiverse這類的開發、設計的社交平臺上，可以的話，就試著使用英文吧！LinkedIn可以分別設中英文履歷，試著好好維護英文履歷的部份，上面現在也可以發表文件，或者也可以試著使用Twitter，這些都是可以試著讓自己寫的英文文件，讓國外開發者看到的地方，也就可以解決沒人看到英文文件，寫了好像等於白寫的問題。

簡單地說，你需要一個編輯可以協助審閱文件，有的人確實會請專業編輯來做這件事，這是最好的情況，不過，多數人在經費上會有所考量。

所幸，現在有一些編輯工具，可以找出基本文法或用字錯誤，甚至提出更好的句型或用字建議，也有像是Grammarly這類的線上文法檢查網站可以使用。

不過，與國外社群互動，從中付出與取得回饋，會是最好的方式。

別擔心笨拙 在與國外社群互動的過程中，有時我會收到一些訊息，一開始就是為他們的笨英文而道歉，其實從我的角度來看，絕大多數都能理解他們想要詢問或要求的內容，相反地，不用擔心自己的英文太笨拙，而不敢試著公開在這類社群中進行互動。

我算不上是英文很好的人，對於英文的表達上，也仍在不斷地修正，然而，最重要的是，為了不要老是談到英文表達就是個痛，多年前我試著開始練習了，畢竟看了再多的英文寫作、文法書，沒開始練習，就什麼都沒有。

就像中文寫作一樣，只要先試著傳達想法，別擔心沒東西可寫或者感到笨拙，也別擔心受到指正，這些都是好事。

就像一開始我舉程式語言學習為例，難道關起門來寫程式，就無人能指正你寫的程式嗎？別忘了，被編譯器指正不是常有的事嗎？就算想感受到笨拙，也要讓世界看到，才能知道自己有多笨拙吧！ 專欄作者 林信良 因在網路上經營「良葛格學習筆記」（openhome.cc）而聞名，曾任昇陽教育訓練中心技術顧問、甲骨文教育訓練中心授權講師，目前為自由工作者，專長為技術寫作、翻譯與教育訓練。

喜好研究程式語言、框架、社群，從中學習設計、典範及文化。

閒暇之餘記錄所學，技術文件涵蓋C/C++、Java、Ruby/Rails、Python、JavaScript、Haskell等多個領域。

熱門新聞 【資安週報】2022年8月1日到8月5日 2022-08-05 DrayTek路由器遭爆含有遠端程式攻擊漏洞 2022-08-05 偷偷加入抓漏競賽的丹麥學生找到Cloudflare未上市服務漏洞 2022-08-05 【資安日報】2022年8月5日，高雄市環保局網站被植入五星旗、國防部與外交部網站再度癱瘓 2022-08-05 思科修補中小企業路由器2重大漏洞 2022-08-05 新一代資安分享標準TLP2.0問世 2022-08-05 微軟更新VSCodePython擴充套件，加入網頁應用程式自動除錯配置 2022-08-05 唐鳳擔任首任數位發展部長，數發部預計8月27日正式掛牌 2022-08-05 Advertisement 專題報導 【iThome2022CIO大調查(上)】企業永續新常態下一步 備份應用的資料減量革命 電子病歷上雲開放了 臺灣數位貨幣新進展 千億營收電商的SRE之旅 更多專題報導