如何寫一份好讀的 API 技術文件？推薦學習技術寫作的好資源 — Documenting APIs
要點新的技能樹了！
我擔任技術寫手 (Technical Writer) 也快 1.5 年了，這段時間寫的都是公司的產品使用手冊操作說明。但是寫久後，發現自己的成長已經停滯了…是時候該升級技術寫手的新技能 — 寫 API 文件。
但是…寫一份清楚好讀的 API 文件真的很難。
相對於產品使用手冊，API 技術文件的學習門檻更高，包含要了解 API 基礎知識 （例如 REST API）、cURL 命令列、JSON Response、前端工程師如何使用 API…等，才能寫出一份好的 API 文件
更難的是，連個線上課程都很難找！
在 Google 搜尋「api documentation tutorial」，跳出來的 Udemy, freeCodeCamp 的課程，真的都…蠻鳥的。這些課程都千篇一律的教你要先從了解讀者是誰、盤點公司內部的 API 有哪些、記得要舉例…等。
我都同意，因為都是…看起來正確的廢話。我極度痛恨這種打高空的教學！
但幸運的是，我在 Write the Doc 這個全球技術寫手的 Slack 頻道中，看到網友推薦 Tom Johnson 的超讚課程-Documenting APIs。
學習這份教材，真的是一個享受！
這份教材有 3 個寫的很好的地方
1. 介紹學習動機
介紹為什麼 Technical Writer 要學習撰寫 REST API 的技術文件，讓學生可以知道學完後到底可以獲得什麼。
厲害的是，他引用了超過 10 個來源的調查數據、寫了 2 篇文章專門分享學習的好處，這讓學習目標變得具體。
2. 分享老師自己的經歷
Tom Johnson 特別花一篇文章的篇幅，介紹自己起初也只是個在學校教寫作的老師，迫於生計壓力才陸續轉職成行銷文案寫手、到現在的技術寫手。
他承認自己不能算是個 Developer，但這不構成自己無法寫高度技術導向的 API 文件。看完介紹，我不但充滿信心、也對這個講師充滿好感，在後面上課也學得很愉快。
3. 列舉詳細的案例，讓學生跟著操作
許多公司不會聘請「技術寫手」，通常都是 PM、業務、客服兼著寫。這些人不是沒有技術背景、就是不會 Coding。但要學習寫 API 文件，怎麼能不知道工程師會如何使用 API 呢？
於是 Tom Johnson 使用 Open Weather 和 Pet Store 這兩個免費的 API 資源，帶領學生實作一個簡單的 HTML、搭配 Javascript jQuery 的 ajax 函式，讓學生可以體會一個前端工程師在拿到 API Response 後，會如何使用在前端網頁的開發上。
我發自內心的讚嘆：
這是我目前看到最好的技術寫作學習教材，除了學到了技術知識外、也學習到一個好課程可以如何設計。
這份教學多達 200 頁，若要影印成 PDF 檔案會是高達 500 頁的份量。這麼好的教材，重點是：免費！
我知道 Technical Writer 在台灣非常冷門，連線上課程、學習書籍也幾乎沒有中文版的。因此分享這個學習資源給有需要的人。
問題是，誰會需要看這個課程呢？
我想到 3 種人
- 技術寫手：不用說，一定要看的。
- 軟體產品經理：你會更了解前後端工程師在開發時需要的產品規格，並且知道自家公司的產品如何跟外部夥伴串接系統。
- 軟體工程師：你可以設身處地的引導使用自家 API 的外部開發者、使用者，給他們一個超讚的使用體驗 (那些寫的不清不楚的 API Doc，真的會讓人血壓飆高)。
課程在此，請自取 👉 Documenting APIs
▶ 關於文章
- 歡迎訂閱 寫作電子報 ，我會跟你分享所有自己在網路上寫作的技巧、故事、經驗。希望你在看完電子報後，能實際去寫、讓更多網路上的人看到你的專業。
- 常滑 Facebook 嗎？可以幫我的 Facebook 粉絲團 按個讚，就可以看到文章啦～
- 想要掌握最新文章，可以點擊下方「Follow」我～
- 如果你覺得文章寫的不錯，可以對文章拍手讓我知道 👏🏻
▶ 關於我
我是朱騏，一個寫作能力超強的軟體技術寫手與產品經理，喜歡研究自媒體寫作、個人知識管理、個人品牌經營。
我可以提供自媒體寫作、個人知識管理、個人品牌經營的
- 1 對 1 諮詢：請參考 1 對 1 諮詢服務
- 講座邀約：請寄 Email 至 contact@chichu.co，並說明主題需求與我討論。
在網路上寫作簡直要你的命了嗎？如果你想要找到自己能寫的主題、在網路上累積自己的專業能見度，你應該聽一個在網路上寫作超過 1000 篇的實戰專家教你怎麼做。(aka 朱騏)
→ I’m Chi 訂閱制：每週分享 2 篇「自媒體寫作」技巧與訣竅文章。教你撰寫高價值的專業內容、製作數位產品的方法，讓你的專業幫助到更多人、賺到被動收入提升營收。
即將進入廣告，捲動後可繼續閱讀
為什麼會看到廣告
留言0
查看全部
你可能也想看
Google News 追蹤
撰寫的API規格書是軟體PM必學技能，能有效提升開發效率並減少溝通誤差。本文分享API規格書從需求收集、設計架構到版本管理。PM不需寫程式，但需理解API邏輯，成為開發與需求方的溝通橋樑，讓專案更順暢、開發團隊更高效！
這篇文章探討了工程師在如何有效提升自己，強調不僅僅是多coding，而是要對程式碼有更深層的理解。隨著職涯發展，工程師需要從單純的技術執行者轉變為團隊領導者，具備解決複雜問題和與他人有效溝通的能力。
我當了記者、新聞主管、廣播主持人，從事新聞工作十多年，文字、口說、表達能力都有一定的水準，雖然常常會興起寫部落格的想法，但都是註冊後 貼個幾篇文章，然後就不了了之
如果連我職涯一開始當記者，後來當過上市公司的公關、行銷、企業高階主管，都不知道該分享什麼給別人，我相信有更多人也會覺得「我要寫什麼?」
JSDoc 全名是 JavaScript Documentation，顧名思義是為 JavaScript 所使用的 API 文件，在程式碼內透過註解的方式撰寫，運行後 JSDoc 會自動掃描註解內容，並生成一份網頁版的文件，對於沒有使用 Typescript 開發的專案，也
API（Application Programming Interface，應用程式介面）可以視為不同軟體系統之間的溝通橋梁，讓雙邊可以交換數據並執行各種功能。這篇會記錄產品經理一定要知道的幾個 API 概念，像是常見的錯誤代碼以及不同的 HTTP 方法（如 PUT、GET、POST）和實際案例說明
※ 什麼是Web API
API 就是後端開出來讓前端來用的介面，讓前端與後端可以溝通。
API流程：
終端使用者用任何一種裝置進入瀏覽器。
瀏覽器透過 API 向後端發出請求，請求查詢或修改資料。
後端透過 API 收到前端的請求後，取得資料並回應給前端。
前端渲染畫面，終端使用者
本文整理了有關技術文件寫作的重要觀念，包括 docs as a product、內容優先，並說明如何構思文件架構。
※ 什麼是 RESTful API？
這種運用 HTTP 來表達語義的路由設計風格稱為 RESTful API，它描述了如何實現 Web API 的架構。所謂的 API 是應用程式介面 (application programming interface)，網址也是一種應用程式的「介面」，故稱為
先前幾篇筆記介紹了網路請求，瀏覽器儲存資料的方式，那麼實務上，前端最常需要發送網路請求的時候，就是透過呼叫 API，去向後端工程師發送/請求資料，所以今天來記錄什麼是 API吧！
嚴格來說，不能算軟體開發分類，畢竟這篇比較像是通知文與心得文，但一定要選個分類，我就選之前常發的類別。
大意其實就只是我的技術文件之後不在 vocus 更新了，可以前往我用 docusaurus 架的網站上看新的技術文章。
撰寫的API規格書是軟體PM必學技能，能有效提升開發效率並減少溝通誤差。本文分享API規格書從需求收集、設計架構到版本管理。PM不需寫程式，但需理解API邏輯，成為開發與需求方的溝通橋樑，讓專案更順暢、開發團隊更高效！
這篇文章探討了工程師在如何有效提升自己，強調不僅僅是多coding，而是要對程式碼有更深層的理解。隨著職涯發展，工程師需要從單純的技術執行者轉變為團隊領導者，具備解決複雜問題和與他人有效溝通的能力。
我當了記者、新聞主管、廣播主持人，從事新聞工作十多年，文字、口說、表達能力都有一定的水準，雖然常常會興起寫部落格的想法，但都是註冊後 貼個幾篇文章，然後就不了了之
如果連我職涯一開始當記者，後來當過上市公司的公關、行銷、企業高階主管，都不知道該分享什麼給別人，我相信有更多人也會覺得「我要寫什麼?」
JSDoc 全名是 JavaScript Documentation，顧名思義是為 JavaScript 所使用的 API 文件，在程式碼內透過註解的方式撰寫，運行後 JSDoc 會自動掃描註解內容，並生成一份網頁版的文件，對於沒有使用 Typescript 開發的專案，也
API（Application Programming Interface，應用程式介面）可以視為不同軟體系統之間的溝通橋梁，讓雙邊可以交換數據並執行各種功能。這篇會記錄產品經理一定要知道的幾個 API 概念，像是常見的錯誤代碼以及不同的 HTTP 方法（如 PUT、GET、POST）和實際案例說明
※ 什麼是Web API
API 就是後端開出來讓前端來用的介面，讓前端與後端可以溝通。
API流程：
終端使用者用任何一種裝置進入瀏覽器。
瀏覽器透過 API 向後端發出請求，請求查詢或修改資料。
後端透過 API 收到前端的請求後，取得資料並回應給前端。
前端渲染畫面，終端使用者
本文整理了有關技術文件寫作的重要觀念，包括 docs as a product、內容優先，並說明如何構思文件架構。
※ 什麼是 RESTful API？
這種運用 HTTP 來表達語義的路由設計風格稱為 RESTful API，它描述了如何實現 Web API 的架構。所謂的 API 是應用程式介面 (application programming interface)，網址也是一種應用程式的「介面」，故稱為
先前幾篇筆記介紹了網路請求，瀏覽器儲存資料的方式，那麼實務上，前端最常需要發送網路請求的時候，就是透過呼叫 API，去向後端工程師發送/請求資料，所以今天來記錄什麼是 API吧！
嚴格來說，不能算軟體開發分類，畢竟這篇比較像是通知文與心得文，但一定要選個分類，我就選之前常發的類別。
大意其實就只是我的技術文件之後不在 vocus 更新了，可以前往我用 docusaurus 架的網站上看新的技術文章。