Tom Johnson 的技術寫作經驗談
更新於 2023/06/17閱讀時間約 4 分鐘
重點整理技術寫手 Tom Johnson 的兩段訪談。
這兩段訪談分別是：
- Technical Documentation with Tom Johnson of Amazon（2022-2-25）
- Tom Johnson: Documenting APIs | Episode 088（2020-12-4）
底下是第一段訪談的重點概要。
關於 Tom Johnson
Tom 目前在 Amazon 擔任技術寫手（technical writer），團隊成員共兩人（包含 Tom），他認為小團隊的好處就是彈性、靈活。
註：也許有人覺得用「技術作家」這個詞顯得更尊重、更好聽一些。這裡用「技術寫手」絲毫沒有貶抑的意思，純粹個人慣用偏好。
Agile 文件寫作流程
Tom 的文件小組採用 Agile 文件寫作流程，每一個衝刺（sprint）為期兩週，並於衝刺結束前展示成果。
Tom 還採用了五個 review 步驟：
- Internal review（內部審閱）
- Product team review（產品團隊審閱）
- Field and support engineer review
- Legal review
- Beta partner review
經歷上述五個審閱程序的技術文件通常都有不錯的品質。
Docs As Code 流程
Tom 認為 Docs as Code 流程應具備以下五個特徵：
- 文件格式：使用 markdown 來編寫文件原稿。
- 內容管理：使用 Git 來進行文件的版本控管。
- 部署方式：持續部署（至 Git）。
- 文字編輯器，例如 Visual Studio Code。（按：原文的 "Test editor" 應是 Document360 網站小編的誤解或誤植。）
- 使用靜態網站產生器來輸出最終成品。（按：例如 Sphinx、Jekyll、Hugo 等等）
補充：只要在 GitHub 上面修改文件的原始碼（原稿），推送至儲存庫之後就能夠自動觸發文件的建置腳本（包含自動檢查文件中的無效連結、不一致的術語、格式等等）。
技術文件的 ROI
Tom 認為許多文件寫作團隊過於倚賴度量數據來評斷文件的品質。比如說，以客戶或技術支 援團隊使用文件的情形來評斷技術文件的 ROI，這種作法有以下問題：
- 如何得知有多少人看了文件卻沒有跟技術支援團隊聯繫？
- 技術支援團隊如何知道自己是因為先前讀了某份技術文件才擁有解決某個問題的知識？
- 如何得知有多少客戶是因為看到文件之後(按：覺得文件寫太差)而拒絕某個專案？
- 如何衡量有多少商業機會是因為技術文件產生的附帶效應、以及實際影響程度多少？
- 如何衡量新進員工透過技術文件而縮短了多少「上手時間」(ramp up time) ？
按：總之，技術文件所產生的價值與回報難以估算。一種常見的方法是在每一份文件當中提供使用者評分機制和提交反饋意見的地方，例如留言板，或者 issue tracker 連結。
技術寫手經常面臨的挑戰
本段來自第二個訪談：Tom Johnson: Documenting APIs | Episode 088，只記下我看到覺得特別有共鳴的地方。
以下開始：
通常技術寫手不是開發者，比較沒有專業的架構設計和工程背景，所以每當碰到需要撰寫技術文件的時候，例如某個 Web API 專案的文件，技術寫手就得忙著趕上與該專案相關的技術，並斟酌該深入到多細的架構設計細節，才足以寫出令目標讀者覺得好讀、有幫助的技術文件。
但如果能看到 API 使用者是如何去使用那些 API 來完成特定 use cases，技術寫手便能比較容易看得出來那些 API 是怎麼彼此兜起來完成一件工作，以及他們的用法是否簡單好用、有哪些值得改進之處，並且更知道該怎麼去解釋與說明那些 API 的用法，才能讓目標讀者覺得閱讀那份技術文件是有幫助的——正好能解決他們的問題，或者節省了他們學習摸索的時間。
因此，為了寫出清晰易讀且內容正確的技術文件，技術寫手通常需要與開發人員密切合作， 以獲取他/她所需要了解的資訊，包括相關的架構、技術，而且通常需要開發人員提供 code samples。此外，技術寫手可能還需要對開發人員提供的 code samples 進行測試，以確保它們都能產生預期的結果。技術文件也需要相關人員審閱（包括開發人員和其他目標讀者），並提供反饋意見，以便持續完善文件內容。
我最近經常在想這些問題，所以在整理重點的時候，難免添加了一些自己的話來延伸和補充，其實 Tom Johnson 在第二段訪談裡面並沒有說那麼多。
Keep writing!
（本文轉載自筆者部落格）
為什麼會看到廣告
14會員
23內容數
這裡有我寫作與自行（獨立）出版電子書的實戰心得與相關知識，包括：寫作與出版工具的使用、各出版平台的比較、電子書上架的逐步教學、行銷技巧、以及持續進行的出版實驗心得與發現。
如果您也想了解如何自行出版電子書，歡迎一起來學習、相互切磋。
留言0
查看全部
你可能也想看
Google News 追蹤
*合作聲明與警語：
本文係由國泰世華銀行邀稿。
證券服務係由國泰世華銀行辦理共同行銷證券經紀開戶業務，定期定額(股)服務由國泰綜合證券提供。
剛出社會的時候，很常在各種 Podcast 或 YouTube 甚至是在朋友間聊天，都會聽到各種市場動態、理財話題，像是：聯準會降息或是近期哪些科
幾乎是互動VR版本的Tom of Finland資料庫，看得出Tom of Finland基金會推廣博物館及Tom of Finland畫作的積極態度與用心。
在面臨緊張議題的時刻，溝通變得更為困難，有時甚至會冒出「我為什麼要聽你的」想法，甚至以懷疑的心態放大拆解說出這句話的這個人背景，說這句話的動機是什麼。
是的，在這個素人都可搭建個人舞台發表高見的年代，專家說的話逐漸不再可靠，既然如此，這群術業有專攻的人影響力何在？
【葉郎每日讀報】20230718
▌葉郎讀報： Tom Cruise 另外兩個不可能的任務——說服罷工對抗中的兩造 ▌
Hollywood Reporter 的消息來源指出，男星 Tom Cruise 曾在上個月以 Zoom 視訊會議方式出席 SAG-AFTRA 美國演員工會和 MPTP 美國電
設計師 Tom Ford 上週無預警發佈「最後女裝系列」告別同名品牌，並於近日宣布新任品牌創意總監將由 Peter Hawkings 出任，執行長則是任命 Guillaume Jesel。
Tom Petty的「American girl」輕快急促的節奏，像是坐著雲霄飛車般的衝擊感，與充斥著情緒高張的生活連結，想起焦慮嚴重的阿輝與躁鬱症母親同住，連兩天接到阿輝咆哮的來電，表示送的便當魚肚有刺，要求主菜魚肚和雞腿交替，隔天再度來電，依然吵著要雞腿便當，情緒勒索的表示：這樣我不要吃；與阿輝
*合作聲明與警語：
本文係由國泰世華銀行邀稿。
證券服務係由國泰世華銀行辦理共同行銷證券經紀開戶業務，定期定額(股)服務由國泰綜合證券提供。
剛出社會的時候，很常在各種 Podcast 或 YouTube 甚至是在朋友間聊天，都會聽到各種市場動態、理財話題，像是：聯準會降息或是近期哪些科
幾乎是互動VR版本的Tom of Finland資料庫，看得出Tom of Finland基金會推廣博物館及Tom of Finland畫作的積極態度與用心。
在面臨緊張議題的時刻，溝通變得更為困難，有時甚至會冒出「我為什麼要聽你的」想法，甚至以懷疑的心態放大拆解說出這句話的這個人背景，說這句話的動機是什麼。
是的，在這個素人都可搭建個人舞台發表高見的年代，專家說的話逐漸不再可靠，既然如此，這群術業有專攻的人影響力何在？
【葉郎每日讀報】20230718
▌葉郎讀報： Tom Cruise 另外兩個不可能的任務——說服罷工對抗中的兩造 ▌
Hollywood Reporter 的消息來源指出，男星 Tom Cruise 曾在上個月以 Zoom 視訊會議方式出席 SAG-AFTRA 美國演員工會和 MPTP 美國電
設計師 Tom Ford 上週無預警發佈「最後女裝系列」告別同名品牌，並於近日宣布新任品牌創意總監將由 Peter Hawkings 出任，執行長則是任命 Guillaume Jesel。
Tom Petty的「American girl」輕快急促的節奏，像是坐著雲霄飛車般的衝擊感，與充斥著情緒高張的生活連結，想起焦慮嚴重的阿輝與躁鬱症母親同住，連兩天接到阿輝咆哮的來電，表示送的便當魚肚有刺，要求主菜魚肚和雞腿交替，隔天再度來電，依然吵著要雞腿便當，情緒勒索的表示：這樣我不要吃；與阿輝