我該怎麼寫？——"Writing for Developers" 閱讀筆記，寫那些讀者想看的東西

你可以把這篇文章視為 2024 年的寫作 SOP 上、下篇 remake 版。除了關於「如何寫」的精華回顧之外，也追加收錄 “Writing for Developers” 一書的「如何寫出受歡迎文章」的寫作技巧。而如果你真的連讀完這篇文章的時間都沒有，那壓縮到極致的懶人包就是——在寫作時以「滿足讀者的需求」為終極目標，並確保讀者能發現文章。

懷著這顆北極星寫作，文章還不受歡迎就不是你的錯了 🌚

在開始寫之前

1. 設定好文章的目標，比如「這是一篇關於Ｘ的文章，預期讀者看完後，他會知道如何執行Ｙ／他會獲得關於Ｚ的知識」；目標會影響文章應該、不應該涵蓋哪些內容
2. 設定好文章的目標讀者是誰，因為這會影響你解說的方式、解說哪些內容
3. 回答「為什麼目標讀者應該看這篇文章」這個問題——你的文章能讓讀者習得新知嗎？你的文章有解決讀者的問題嗎？如果都沒有，那你期待讀者看完文章會得到什麼？

確認好以上三件事情後，就可以開始寫作了。

寫作時的注意事項

在系列文的第二篇〈我該寫什麼？〉曾提過，受歡迎的文章都會遵守 flow/focus/fact 規則，而整個寫作過程其實就是在完善這三件事：

• 在草稿階段確認文章以合理的流程（flow）揭露內容
• 在內容填充階段確認所有內容都與文章目標有關（focus）
• 在精修階段確認內容都是事實（fact）

草稿階段

此階段的目標是確認文章結構、安排內容順序。關於建立文章結構的詳細處理方式，可參考寫作ＳＯＰ上篇。如果你實在沒空：

• 根據文章目標列出大綱，並確保所有的大綱都與「達成文章目標」有關
• 根據因果或重要度排列大綱，確保讀者在閱讀時，能循序漸進地了解他該知道的事

當你認為文章的結構與內容的揭露順序已經完善時，就可以進入下一階段。對自己沒有自信的朋友，可以參考 “Writing for Developers” 的建議，將大綱餵給生成式 AI 並詠唱以下咒語：

• Does this draft have any logical gaps?
• Can you identify any parts of this draft that seem less relevant to its main goal of “your writing goal”?

內容填充階段

此階段的目標是將大綱發展為段落，再將段落組成文章；並確保所有內容都與文章目標有關。每一個句子都要提供新資訊，沒有提供新資訊的句子就該被刪掉。

如果你真的寫到不能自己，又覺得這些好像有點離題的內容還有一點殘存價值，那就以後記、補充區塊的形式來安置這些內容。

而以下是來自 “Writing for Developers” 的，關於「如何寫出受歡迎文章」的建議：

• 務必要撰寫前言
  • 目的是讓讀者知道他們能從這篇文章收穫什麼，設定好讀者的預期
  • 如果你的文章是在討論其他人已經寫過的主題，那就在前言告訴讀者你為什麼要寫這篇文章？你的文章和其他人有什麼不一樣的地方？
• 提供目錄，且確保每一個章節都能單獨閱讀¹
  • 目的是讓讀者可以直接進入他最關心的主題，且不強迫他看完所有內容
• 務必要撰寫結尾
  • 目的一是幫讀者摘錄所有重點；想要文章受歡迎，那這份對讀者的體貼就非常重要
  • 目的二是創造互動；你可以在結尾說明你的下一步（系列文的規劃、專案的 roadmap），或是引導讀者採取行動（實際動手嘗試文中程式碼、點擊 CTA 或甚至是投遞履歷⋯⋯如果你在寫一篇宣傳自家產品的技術文章 🌚）
• 不用永遠遵守「從頭到尾」的寫作順序，你可以從草稿中的任何一個大綱開始填充內容

當你認為整篇文章已經說完你想傳達的全部內容後，就可以開始精修了。如果你真的不確定文章是否還有需要補充的部分，一樣可以請生成式 AI 幫忙檢查：

• Are there any paragraphs in this article that require additional detail?
• Are there any awkward transitions in this article?

精修階段

此階段的目標是確保文章內容全部都是事實。刪掉所有臆測、沒有證據支持的內容。如果真的無法避免推測，請明示讀者有哪些內容是「基於手頭證據的推測」。以及檢查每一個專有名詞、成語、俚語，確保你沒有誤用它們。

很遺憾，只要生成式 AI 還有幻想的問題，這步驟的工作就無法請 AI 效勞。

在文章發佈之前

檢查表面項目

在寫作的ＳＯＰ下篇，我曾提過一篇好文章除了要有說服力以外，也應該要寫得好懂。當時主要的兩個檢查方向如下：

• 是否用了太多冷僻字（以至於打斷閱讀節奏）
• 儘管沒有文法錯誤，但語氣卻無法與文章主題搭配（比如在討論輕鬆的主題，卻使用太過正式的文字）

但對 “Writing for Developers” 來說，只有滿足以上兩點是不足以讓文章受歡迎的。對目的是讓文章被愛戴並廣傳的你，請在發布前檢查文章是否滿足以下關於文字與圖片的標準。

一、關於文字：

請檢查標題在各種裝置上都沒有在奇怪的地方斷句。確保你提供的程式碼小抄（code snippet）能渲染該語言的關鍵字和語法（syntax）。更好的做法是嵌入讓使用者能直接和程式碼互動的元件，比如 StackBlitz 或 Sandpack。

用有意義的片語來描述超連結。

…ensure that the hyperlinked text describes the linked item and tells your reader what to expect.

不要只寫「點『這裡』查看更多資訊」，而是告訴使用者這個「這裡」到底會連到什麼內容。比如「如果想知道更多實作細節，可參考『框架 X 官方針對功能 Y 的詳細說明』」。理由是：

• 讓讀者只靠你的文字就能判斷他是否需要連結內的額外資訊
• 確保網站無障礙（web accessibility），只寫「這裡」或「直接貼出網址」都會讓螢幕閱讀器的使用者體驗很差

關於文字的最後一點——請確保文章裡的所有連結都能點開，而且都連結到有效的內容。可以用任何你偏好的 Broken Link Checker 來檢查。

二、關於圖片：

• 文章中的圖片在各種裝置看起來的效果都好嗎？如果圖片裡有文字，字會不會被切掉，或是小到看不清楚？
• 要為圖片設定有意義的 alt，內容要能做到「當圖片掛掉時，讀者多少還能透過 alt 推測圖片要傳遞的資訊」

檢查後設內容

經過以上檢查以後，你的文章應該會看起來像個絕代佳人。但還沒完，畢竟如果讀者不知道你寫了篇文章，文章就不可能受歡迎。而以下是 “Writing for Developers” 一書裡，關於「如何讓文章最大限度的被曝光、盡可能觸及所有讀者」的三種方法。

一、設定關鍵字：

先想想使用者在搜尋哪些關鍵字時，你的文章能幫到他們。

What might motivate the user to seek an article on the topic you wrote about?

真的沒有任何靈感，請考慮詢問生成式 AI “What are some good SEO keywords for this blog post?”，或是參考《資訊架構學》（第四版）關於「尋找」的說明——根據你想滿足的搜尋情境，來判斷要為文章提供哪些關鍵字。

關鍵字應該要出現在文章的網址與 meta 標籤中。

二、設定標籤：

如果文章發在 Medium 這種有標籤，且可以讓人訂閱的平台，就根據文章內容挑選關聯高、曝光度高的標籤。標籤的訂閱基數不一定要選最多的，因為和你競爭讀者注意力的對手也多。只要標籤的訂閱基數不要太差——只要文章品質精良——你反而有機會鶴立雞群。

三、提供社交平台分享按鈕與 RSS 訂閱功能，這能讓你的文章有更多機會被擴散。

總結：受歡迎的本質是在乎

在閱讀 “Writing for Developers” 時，一直有種「與其說是關於寫作，它更像是一本行銷的教科書」的感覺。如果你的終極目標是寫出被廣傳的文章、成為圈子中的名人，那這本書就值得你花時間精讀一遍（但我很高興你還是把這篇筆記讀完了，謝謝）。

🥹：但這本書是英文 ⋯⋯ 而且你自己都在這篇文章裡提到「受歡迎的文章會在結尾幫讀者做懶人包」了，你不會在這邊到此為止對吧？

🦊：打自己臉不是什麼稀奇的事情，但作為一個寫作者，我的確不能允許自己在同一篇文章裡做出與文章內容衝突的事。以下是「如何寫出受歡迎文章」的懶人包：

1. 文章必定要能解決讀者的需求
2. 文章內容要以合理的順序揭露，並全部都與文章主題有關，且僅陳述事實
3. 確保文章以最順眼的方式出現在讀者眼前（連結都活著嗎？圖片會不會太小張？）
4. 設定關鍵字、標籤，確保文章能被讀者看見

說真的，寫一篇受歡迎的文章挺累人的。

註解

1. 是的，連寫作都要遵守高內聚、低耦合的規範。 ↩