我該寫什麼？——"Writing for Developers" 閱讀筆記，日常的又恨又愛

前言

這篇是 “Writing for Developers” 一書的系列分享文之二。這篇的重點是「不論你是技術寫作的新手或老手，都可以從這篇文章得到一些關於寫作題材的靈感」。

如果你現在還不確定是否要開始寫作，可以移駕系列文第一篇 我該不該寫？ 來考慮是否參加救援任務開始寫作。如果你已經下定決心，但不確定自己可以寫些什麼，那就繼續看下去吧 🌚

如果你剛開始嘗試寫作

對於技術寫作新手，我推薦從以下兩種主題開始：

1. 寫你很有感情的主題
2. 如果你的開發生活一時半刻沒有激情，那就寫教學文件

寫你很有感情的主題

🤨：什麼叫很有感情的主題？

🦊：在這篇文章的脈絡下，「很有感情的主題」指的是那些你一想到就會覺得心情澎湃、充滿喜悅，或是一想到就憤恨難平、充滿怨言的開發事件。比如你遇見了命中註定的套件，彷彿什麼問題都可以靠它解決；或是你遇到堪稱業障的框架，你奮戰了三天三夜才發現問題出在搞錯參數單位。

總之，就是那些燃燒你的靈魂，讓你印象深刻（不論是愛或恨）的主題。

🤨：為什麼要推薦新手寫這類主題？

🦊：畢竟「請你寫心目中輕如鴻毛的主題」跟「請你寫刻骨銘心的開發故事」會產生兩種截然不同的心情——你都要花時間寫字了，在人生有限的情況下，寫那些對你來說很深刻的事情會比較有吸引力吧。

而且，既然是寫作新手，那在你習慣、愛上寫作前，還是盡可能排除那些會讓人覺得無聊（進而放棄寫作）的可能性比較好。

🤨：那這些「讓人印象深刻的主題」要如何發展成一篇文章？

🦊：假設你在開發時與工具Ｘ相遇，發現它是如此神奇，用優雅又簡便的方式就能達成你的需求。那在透過寫作分享你對工具Ｘ的熱愛時，可以從以下描述發展成一篇文章：

• 我非常推薦開始使用工具Ｘ，因為它的特性Ｙ非常善於處理類型Ｚ的需求⋯⋯
• 我用工具Ｘ做出了成果Ｙ，這篇文章會分享我為何選擇使用工具Ｘ，以及如何透過它完成Ｙ，途中我如何克服技術限制Ｚ⋯⋯

而如果你在開發過程被工具Ｘ雷的七葷八素，認為自己有義務讓全世界知道你曾經歷過什麼，或是你認為多救一個人免於工具Ｘ的毒手也是在做功德。那在寫作時可以從以下角度切入：

• 我不推薦工具Ｘ，因為它的特性Ｙ並不擅長處理類型Ｚ的需求⋯⋯
• 當我嘗試使用工具Ｘ解決類型Ｙ的問題時，我遇到問題Ｚ，而我如何解決問題Ｚ⋯⋯

🤨：我怎麼知道文章要寫到什麼程度才算「有寫完」？

🦊：以推薦（反推薦）文來說，只要能提出客觀證據來證明你對工具Ｘ的熱愛（痛恨）有其道理，那這就是一篇「有寫完」的技術文章。

而如果你的文章是在描述如何使用工具Ｘ完成Ｙ（或克服問題Ｚ），那只要讀者在看完你的文章後，能在自己的機器上重現出相同的結果，我認為這篇文章就是「有寫完」了。

寫教學文件

🤨：為什麼會建議技術寫作新手寫教學文件啊？我新手欸！

🦊：事實上教學文件是非常單純、好入門的寫作主題。我的理由如下：

1. 教學文件的目標非常明確，當你在撰寫文章時，只要先定好目標，並專注於「讓文章能幫助讀者實現目標」就好；而要判斷文章有沒有「寫完」也非常客觀——只要讀者看完文章能理解、並且在他的環境裡也能完成文章目標，那這篇文章就能說是有寫完
2. 你可以自行決定目標Ｘ的規模；在開始技術寫作的初期，你可以將目標先設定成「如何在 vite 專案執行以 TypeScript 撰寫的單元測試」這類相對小型、簡單的目標；習慣寫作後，再提升目標的規模
3. 這類文章有不錯的拓展性——當你說明如何達成目標Ｘ後，你可以進一步說明為什麼你需要達成目標Ｘ、為什麼選擇技術Ｙ來達成目標Ｘ、目前用來達成目標Ｘ的手段有沒有副作用⋯⋯等等——同一個主題有很多可以追加討論的部分，你不需要一直想辦法挖掘新的寫作題材

當你的開發生活沒有太多速度與激情，但又想嘗試技術寫作時，可以先從這類型的文章開始練習。

🤨：好吧，那寫教學文件有什麼要注意的事情嗎？

🦊：以讀者的立場來說，最怕花了時間卻得不到幫助，所以建議教學文件必備以下資訊。

1. 這篇文章的發佈日期，或你最後更新文章內容的日期；在軟體快速迭代的現在，教學文可能很快就會過期，而提供日期能讓讀者決定他是否要繼續花時間看下去
2. 這篇文章適用於哪一個版本；理由同上，有些流程在軟體更版後可能已經不適用，標註版本能讓讀者自行判斷是否要花時間閱讀
3. 你的環境資訊與設定；不同的環境可能會有不同的流程，你不用為每一個環境都寫一套教學，但至少讓讀者知道這篇文章是寫給哪一個環境的使用者看的

如果你希望文章能受歡迎

😠：我已經不是菜鳥了，現在請告訴我要寫什麼主題才能讓文章受歡迎！

🦊：要回答這個問題，得要先知道為什麼人會去讀技術文章，畢竟文章要先被讀了才有機會被喜愛、被分享，進而被認為是受歡迎。而 “Writing for Developers” 一書認為，這個「為什麼」不外乎為以下兩點：

1. 讀者想獲得關於某個領域最新，或最深入的資訊
2. 讀者遇到、並且需要解決他的技術問題

Reading such (tech) blog posts is a primary means of tracking what’s new, solving problems, and deepening domain expertise.

因此，想要讓技術文章受歡迎，你的文章就要能讓讀者知道：

1. 關於某個軟體最即時的介紹，或最深入的分析
2. 當他遇到某個問題時，應該如何解決，或甚至如何避免未來再度遇到類似的問題

亦即你的寫作必定會從「能讓人習得新知」或「解決問題」兩者擇一的主題上展開，並且要確保文章會被潛在的讀者發現。

😠：道理我都懂，但你能不能舉一些具體的例子啊？

🦊：詳細的執行細節會在下一篇文章介紹，我先在此提供幾個寫作時要注意的部分。

標題要引人注目

不論是 Google 的搜尋結果或是各種討論區，潛在讀者能馬上看到的，基本上只有文章標題。而當讀者心中有所期待，並且你的文章標題看起來能解決他的需求時，文章被點開來看的可能性就會大幅上升。

舉例如下：

• 使用者想知道「怎麼在 vite 專案跑 TypeScript 測試」，而你的文章標題是「三個步驟讓 vite 專案能跑 TS 測試」
• 使用者不明白「為什麼我的 @mui 元件在 remix app 裡無法正常顯示樣式」，而你的文章標題是「如何讓 remix app 順利渲染 @mui 元件」

而如果你不介意走炎上行銷，那為文章設定一個十分挑釁的標題也是個手段。比如你靈光乍現，察覺如果 jQuery 到現在都還有人在使用¹，那必定是有它優秀、難以被取代的部分，值得挖掘一番。所以你做了好些研究，揮毫千字，最後將文章的標題訂為「2025 年了誰還在用 jQuery」然後滴進名為社群媒體的鯊魚池中²。

內容要精雕細琢

如果一篇文章只有標題吸引人，實則內容乾枯，那它只能說是很引人注目，而不會說是受歡迎。根據 “Writing for Developers” 的理論，受歡迎的技術文章會有以下三種特徵：

1. 它回答了讀者關心的問題
2. 它有效率地回答了問題
3. 它讀起來很舒服

要回答讀者關心的問題

先來看看 “Writing for Developers” 認為適合當作技術文章的主題（部分舉例）：

• 你打造了什麼：你如何、為何決定要打造某個 side project
• 你重寫了什麼：你為何決定用某個新技術改寫老專案
• 你學到的教訓：你滿意那個轉換為新技術的老專案嗎？為什麼（不）；你捅過哪些簍子，最後又是如何補救的
• 獨特的想法：你對目前最受社群歡迎的新技術有什麼看法；你現在如何看待那個兩年前的 side project 呢
• 偉大的數據：你如何進一步壓縮專案的編譯、打包時間

雖然上方列舉的主題在表面上都以作者本身為出發點，但文章的核心其實都是在回答讀者心目中的「發生了什麼事；為什麼會發生這件事；你為什麽會這樣想；你是如何做到的」疑問。要抓住讀者的心，首先要讓他覺得這篇文章和他切身相關、不得不看。

要有效率地提供正解

畢竟技術文章的讀者都有自己的目標，那能越有效率地滿足讀者的文章，自然更容易受到歡迎。在寫作時應注意以下部分：

• 講求事實（fact）——討論技術細節時，只描述客觀事實，不臆測、不腦補；在分享新工具、新技術的使用心得時，務必告訴讀者你是因為哪些客觀的原因，所以才得出哪些主觀的結論
• 精練內容（focus）——不要寫讀者已經知道的內容；所以在寫作前，要先確認你是為了哪些讀者而寫？是沒有太多技術知識的新手，還是歷戰工程師？畢竟這兩類讀者的「已知」可是天差地遠
• 合理發展（flow）——以有邏輯的方式來揭露所有你想發表的內容，舉例：如果在安裝套件前要先處理環境設定，那就先在文章內說明環境的設定方式，再告訴讀者如何進行安裝

勇者一定也會認同這種寫作方式的。

要好讀

滿足「講求事實、內容精煉、發展合理」這三點之後，請記得檢查你的文章是否好讀。標準很簡單：問自己是否能心甘情願地讀完整篇文章？如果不行，就調整那些讓你讀不下去的段落。

如果連作者自己都看不下去，那陌生的讀者更是沒有理由接受這篇文章。請試著在發表文章之前，把內容整理到自己都能開心品嚐的程度。要先讓讀者喜歡它，文章才有機會受歡迎。

結論

對寫作新手來說，任何讓你印象深刻的主題都能發展成一篇技術文章。先從自己非常有興致的主題開始，會比較容易養成寫作習慣。而如果你手邊暫時沒有這樣的題材，那可以考慮寫教學文件——因為這類文章只要能幫助讀者達成你在文中設定好的目標，它就可以算是「有寫完」了。再來，教學文有不錯的拓展性，你可以從教學文的主角延伸出「為什麼我選擇這個技術當主角」、「是否有其他代換品」等文章，不用花太多時間尋找新的寫作主題。

而對於想讓自己作品受歡迎的寫作老手，那題材的選擇就相對有所限制了。因為人會去讀技術文章，不外乎想學點新東西，或是遇到問題需要解答。所以如果你的目標是寫出爆文，那就先考慮寫能幫助到讀者的主題吧。

後記

儘管在上一篇預告過「下一篇部落格文章會說明技術文章的幾種常見模式，以及各種日常開發事件適合發展成什麼類型的技術文章」，但在完成這篇文章後，發現實在難以在合理的脈絡下安排「關於技術文章的常見模式說明」，請原諒我將這個主題繼續往後延 🥹

註解

1. Stack Overflow 每天至少有一篇關於 jQuery 的提問 ↩

2. 請在充分衡量可能引起的結果與代價後，再決定是否使用挑釁標題。本文僅出自傳遞知識的立場讓讀者知道「採用挑釁的標題也是一種能讓文章引起關注的手段」。並不代表我鼓勵讀者採用這種方式來制定文章標題 🌚 ↩