How to write a good API documentation? API documentation tutorials recommendation

如何寫一份好讀的 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 個寫的好的地方

介紹學習動機：介紹為什麼 Technical Writer 要學習撰寫 REST API 的技術文件，讓學生可以知道學完後到底可以獲得什麼。厲害的是，他引用了超過 10 個來源的調查數據、寫了 2 篇文章專門分享學習的好處，這讓學習目標變得具體。
分享老師自己的經歷：Tom Johnson 特別花一篇文章的篇幅，介紹自己起初也只是個在學校教寫作的老師，迫於生計壓力才陸續轉職成行銷文案寫手、到現在的技術寫手。他承認自己不能算是個 Developer，但這不構成自己無法寫高度技術導向的 API 文件。看完介紹，我不但充滿信心、也對這個講師充滿好感，在後面上課也學得很愉快。
列舉詳細的案例，讓學生跟著操作：許多公司不會聘請「技術寫手」，通常都是 PM、業務、客服兼著寫。這些人不是沒有技術背景、就是不會 Coding。但要學習寫 API 文件，怎麼能不知道工程師會如何使用 API 呢？於是 Tom Johnson 使用 Open Weather 和 Pet Store 這兩個免費的 API 資源，帶領學生實作一個簡單的 HTML、搭配 Javascript jQuery 的 ajax 函式，讓學生可以體會一個前端工程師在拿到 API Response 後，會如何使用在前端網頁的開發上。

我發自內心的讚嘆：

這是我目前看到最好的技術寫作學習教材，除了學到了技術知識外、也學習到一個好課程可以如何設計。

這份教學多達 200 頁，若要影印成 PDF 檔案會是高達 500 頁的份量。這麼好的教材，重點是：免費！

我知道 Technical Writer 在台灣非常冷門，連線上課程、學習書籍也幾乎沒有中文版的。因此分享這個學習資源給有需要的人。

問題是，誰會需要看這個課程呢？

我想到 3 種人

課程在這裡

Last updated 1 year ago