如何寫一份好讀的 API 技術文件?推薦學習技術寫作的好資源 — Documenting APIs

閱讀時間約 5 分鐘

要點新的技能樹了!

我擔任技術寫手 (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 篇「自媒體寫作」技巧與訣竅文章。教你撰寫高價值的專業內容、製作數位產品的方法,讓你的專業幫助到更多人、賺到被動收入提升營收。
210會員
129內容數
分享學習相關的技巧、工具與方法
留言0
查看全部
發表第一個留言支持創作者!
朱騏的沙龍 的其他內容
對公司團隊來說,培養「寫文件」文化是非常棒的事情。例如降低新人 onboarding 時的教育成本、跨團隊溝通的時間成本。但多數的人都覺得「寫文件」是一件麻煩的事情。如果公司團隊要開始推行「寫文件」文化,應該如何做呢? 我有 6 點建議。
「為什麼非產品部門的同事,對產品操作會這麼不熟悉呢?」這是許多產品團隊都可能遭遇的問題。這篇文章分享我在公司舉辦 Workshop (工作坊)的經驗。包含 3 部分:(1) 為什麼要舉辦 Workshop? (2) 如何準備 Workshop?(3) 我從 Workshop 學到的 3 點經驗教訓
SaaS 公司提供即時、線上的軟體產品/服務,因此讓小白使用者「好上手」是非常重要的。但使用者卡關時怎麼辦?一個不用浪費公司太多人力、又能讓使用者快速排除問題的方法就是:「提供技術文件」。如果你的公司內部/產品團隊沒有專門的Technical Writer,看完這篇文章可以讓你了解 4 種產品必要的
我曾經擔任 PM 將近 6 年的時間、在新職位 - Technical Writer 工作 9 個月的時間,這篇文章分享關於「寫文件」這件事 - 包含 Technical Writer 在做些什麼、跟「產品經理(Product Manager)」的差異。如果你對軟體產業有興趣,一起來看看這篇文章吧。
換新工作滿半年了,這是我入職場7年第一次轉換不同職能的工作,在心境上有很多的感觸跟自我對話,其中最重要的就是「身份認同」這件事情,這篇文章分享 4 點感觸給同為想要轉換職能的人。
對公司團隊來說,培養「寫文件」文化是非常棒的事情。例如降低新人 onboarding 時的教育成本、跨團隊溝通的時間成本。但多數的人都覺得「寫文件」是一件麻煩的事情。如果公司團隊要開始推行「寫文件」文化,應該如何做呢? 我有 6 點建議。
「為什麼非產品部門的同事,對產品操作會這麼不熟悉呢?」這是許多產品團隊都可能遭遇的問題。這篇文章分享我在公司舉辦 Workshop (工作坊)的經驗。包含 3 部分:(1) 為什麼要舉辦 Workshop? (2) 如何準備 Workshop?(3) 我從 Workshop 學到的 3 點經驗教訓
SaaS 公司提供即時、線上的軟體產品/服務,因此讓小白使用者「好上手」是非常重要的。但使用者卡關時怎麼辦?一個不用浪費公司太多人力、又能讓使用者快速排除問題的方法就是:「提供技術文件」。如果你的公司內部/產品團隊沒有專門的Technical Writer,看完這篇文章可以讓你了解 4 種產品必要的
我曾經擔任 PM 將近 6 年的時間、在新職位 - Technical Writer 工作 9 個月的時間,這篇文章分享關於「寫文件」這件事 - 包含 Technical Writer 在做些什麼、跟「產品經理(Product Manager)」的差異。如果你對軟體產業有興趣,一起來看看這篇文章吧。
換新工作滿半年了,這是我入職場7年第一次轉換不同職能的工作,在心境上有很多的感觸跟自我對話,其中最重要的就是「身份認同」這件事情,這篇文章分享 4 點感觸給同為想要轉換職能的人。
你可能也想看
Google News 追蹤
Thumbnail
這個秋,Chill 嗨嗨!穿搭美美去賞楓,裝備款款去露營⋯⋯你的秋天怎麼過?秋日 To Do List 等你分享! 秋季全站徵文,我們準備了五個創作主題,參賽還有機會獲得「火烤兩用鍋」,一起來看看如何參加吧~
Thumbnail
11/20日NVDA即將公布最新一期的財報, 今天Sell Side的分析師, 開始調高目標價, 市場的股價也開始反應, 未來一週NVDA將重新回到美股市場的焦點, 今天我們要分析NVDA Sell Side怎麼看待這次NVDA的財報預測, 以及實際上Buy Side的倉位及操作, 從
Thumbnail
Hi 大家好,我是Ethan😊 相近大家都知道保濕是皮膚保養中最基本,也是最重要的一步。無論是在畫室裡長時間對著畫布,還是在旅途中面對各種氣候變化,保持皮膚的水分平衡對我來說至關重要。保濕化妝水不僅能迅速為皮膚補水,還能提升後續保養品的吸收效率。 曾經,我的保養程序簡單到只包括清潔和隨意上乳液
Thumbnail
在投稿研究時,常常遇到很會拖的期刊,這時寫信去了解研究稿件進度至關重要。然而對於英文不是母語的人來說,寫英文信件是不容易的。本文將教您如何撰寫一封詢問研究進度的英文信件,並提供一個信件模板範例。
Thumbnail
本文介紹了作者William Zinsser的回憶錄寫作教學書《如何寫出好人生》。書中不僅包含作者的回憶錄,還穿插了寫作教學,讀後令人留下深刻印象。作者提出的寫作方式也啟發了讀者寫回憶錄的想法,推薦給正在寫回憶錄或未來想寫回憶錄的人。
Thumbnail
繼如何撰寫一份創業計畫書 增加政府創業補助申請的過件率(上篇)針對計畫內容在研發動機、競爭力分析-技術/產品/服務優勢比較以及可行性分析等三大重點進行深入的探討後,接下來要談的便是進入一般政府創業補助案申請最大的重點: 核銷經費編列及補助款編列
Thumbnail
目前在國內凡是新創公司,用到創業計畫書的情境可說非常廣泛,舉凡找尋天使投資人、申請創業貸款、上募資平台、進駐加速器,乃至我們接下來要介紹的政府創業補助申請,都不乏需要一份面面俱道的營運計畫書或創業計畫書,以下我們就 政府創業補助申請的面向,來探討要該如何撰寫創業計畫書才能增加政府創業補助的過件率?
Thumbnail
投行專案推進過程中,總是有很多很多的事項需要溝通討論,牽扯各家中介機構、公司等各方;就某些具體又重要複雜的問題,免不了要給客戶進行詳細分析或是作為會議溝通檔案,一般都是以備忘錄的形式;剛開始覺得不習慣,現在覺得是一個非常好的形式,比PPT實在多了,聽說🇺🇸某廠開始使用Word檔而不是PPT進行會
Thumbnail
我曾經是一個月要寫好幾份企劃書的人,每一本都是字多又厚,參與政府的標案通常都是通宵達旦的寫,曾經一連三天沒睡就是為了標案!政府標案的企劃到底長得甚麼樣?你們在網路上找得到範例嗎?頁數要求幾頁?份數要求幾份?用甚麼檔案格式?如果你不是公關公司,你是沒有參考的範例,這些標案企劃是不會外流的,你也沒有機會
Thumbnail
又到了求職季,想必很多新鮮人都在為寫履歷而苦惱;又或者你想轉職、跨領域,卻不知道怎麼將過往經驗聚焦,寫出一份好的履歷嗎? 一份好的履歷,不僅能與其他申請者做出差異化,也大大增加 HR 聯繫你的機會,今天來跟大家分享如何寫出一份HR最愛的履歷
Thumbnail
☎️先上我在知乎的數據: 目前每篇回答的閱讀數平均約為22萬,以知乎2億用戶的數據來說,我又是單打獨斗,沒有團隊操作,成績算是相當好了。 目前關注我的人數:  除了以上數據外,還上了無數次的全站熱門內容。 最近一篇: 如我在其他文章裡說過,不管在哪寫文我都沒有抱團(ps:抱團是個人自由)操作任
Thumbnail
本系列文章的最後一篇。希望這個系列的文章能成為有志於學寫文案、成為國際行銷人的讀者們,在進一步理解基本文字技巧、進入多語思考的層次、並學習「語言行銷」這個領域的起點。
Thumbnail
先前求職時,有認真研究一波如何寫份不錯的履歷,不錯指的是能不浮誇的顯露自身優點,讓求才方能先透過履歷對求職者有一定的認識,並進而取得符合雙方需求的面試機會。
Thumbnail
這個秋,Chill 嗨嗨!穿搭美美去賞楓,裝備款款去露營⋯⋯你的秋天怎麼過?秋日 To Do List 等你分享! 秋季全站徵文,我們準備了五個創作主題,參賽還有機會獲得「火烤兩用鍋」,一起來看看如何參加吧~
Thumbnail
11/20日NVDA即將公布最新一期的財報, 今天Sell Side的分析師, 開始調高目標價, 市場的股價也開始反應, 未來一週NVDA將重新回到美股市場的焦點, 今天我們要分析NVDA Sell Side怎麼看待這次NVDA的財報預測, 以及實際上Buy Side的倉位及操作, 從
Thumbnail
Hi 大家好,我是Ethan😊 相近大家都知道保濕是皮膚保養中最基本,也是最重要的一步。無論是在畫室裡長時間對著畫布,還是在旅途中面對各種氣候變化,保持皮膚的水分平衡對我來說至關重要。保濕化妝水不僅能迅速為皮膚補水,還能提升後續保養品的吸收效率。 曾經,我的保養程序簡單到只包括清潔和隨意上乳液
Thumbnail
在投稿研究時,常常遇到很會拖的期刊,這時寫信去了解研究稿件進度至關重要。然而對於英文不是母語的人來說,寫英文信件是不容易的。本文將教您如何撰寫一封詢問研究進度的英文信件,並提供一個信件模板範例。
Thumbnail
本文介紹了作者William Zinsser的回憶錄寫作教學書《如何寫出好人生》。書中不僅包含作者的回憶錄,還穿插了寫作教學,讀後令人留下深刻印象。作者提出的寫作方式也啟發了讀者寫回憶錄的想法,推薦給正在寫回憶錄或未來想寫回憶錄的人。
Thumbnail
繼如何撰寫一份創業計畫書 增加政府創業補助申請的過件率(上篇)針對計畫內容在研發動機、競爭力分析-技術/產品/服務優勢比較以及可行性分析等三大重點進行深入的探討後,接下來要談的便是進入一般政府創業補助案申請最大的重點: 核銷經費編列及補助款編列
Thumbnail
目前在國內凡是新創公司,用到創業計畫書的情境可說非常廣泛,舉凡找尋天使投資人、申請創業貸款、上募資平台、進駐加速器,乃至我們接下來要介紹的政府創業補助申請,都不乏需要一份面面俱道的營運計畫書或創業計畫書,以下我們就 政府創業補助申請的面向,來探討要該如何撰寫創業計畫書才能增加政府創業補助的過件率?
Thumbnail
投行專案推進過程中,總是有很多很多的事項需要溝通討論,牽扯各家中介機構、公司等各方;就某些具體又重要複雜的問題,免不了要給客戶進行詳細分析或是作為會議溝通檔案,一般都是以備忘錄的形式;剛開始覺得不習慣,現在覺得是一個非常好的形式,比PPT實在多了,聽說🇺🇸某廠開始使用Word檔而不是PPT進行會
Thumbnail
我曾經是一個月要寫好幾份企劃書的人,每一本都是字多又厚,參與政府的標案通常都是通宵達旦的寫,曾經一連三天沒睡就是為了標案!政府標案的企劃到底長得甚麼樣?你們在網路上找得到範例嗎?頁數要求幾頁?份數要求幾份?用甚麼檔案格式?如果你不是公關公司,你是沒有參考的範例,這些標案企劃是不會外流的,你也沒有機會
Thumbnail
又到了求職季,想必很多新鮮人都在為寫履歷而苦惱;又或者你想轉職、跨領域,卻不知道怎麼將過往經驗聚焦,寫出一份好的履歷嗎? 一份好的履歷,不僅能與其他申請者做出差異化,也大大增加 HR 聯繫你的機會,今天來跟大家分享如何寫出一份HR最愛的履歷
Thumbnail
☎️先上我在知乎的數據: 目前每篇回答的閱讀數平均約為22萬,以知乎2億用戶的數據來說,我又是單打獨斗,沒有團隊操作,成績算是相當好了。 目前關注我的人數:  除了以上數據外,還上了無數次的全站熱門內容。 最近一篇: 如我在其他文章裡說過,不管在哪寫文我都沒有抱團(ps:抱團是個人自由)操作任
Thumbnail
本系列文章的最後一篇。希望這個系列的文章能成為有志於學寫文案、成為國際行銷人的讀者們,在進一步理解基本文字技巧、進入多語思考的層次、並學習「語言行銷」這個領域的起點。
Thumbnail
先前求職時,有認真研究一波如何寫份不錯的履歷,不錯指的是能不浮誇的顯露自身優點,讓求才方能先透過履歷對求職者有一定的認識,並進而取得符合雙方需求的面試機會。