Tom Johnson 的技術寫作經驗談
重點整理技術寫手 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 追蹤
嘿，大家新年快樂~ 新年大家都在做什麼呢？
跨年夜的我趕工製作某個外包設計案，在工作告一段落時趕上倒數。
然後和兩個小孩過了一個忙亂的元旦。在深夜時刻，看到朋友傳來的解籤網站，興致勃勃熬夜體驗了一下，覺得非常好玩，或許有人玩過了，但還是想寫上來分享紀錄一下~
這篇文章探討了工程師在如何有效提升自己，強調不僅僅是多coding，而是要對程式碼有更深層的理解。隨著職涯發展，工程師需要從單純的技術執行者轉變為團隊領導者，具備解決複雜問題和與他人有效溝通的能力。
改稿真的不是一件需要太多情緒的事，把錯的挑出來、改掉，就這麼簡單！很少有什麼「大錯」需要去爭執誰對誰錯。不過真的滿多時候鬼遮眼或是偶爾真的會發生某種「明明前一版是對的，這一版居然是錯的」的鬼故事，把問題找出來解決就好！
實際就業後，會發現收集與分析需求，通常都不是工程師在做，會有另一群人，以非工程的角度收集及分析需求，然後在開發過程中蹦出不同的火花，於是很好奇另一群人的想法是什麼？我不敢說這本書能完全代表另一群人的想法，但確實能夠得到很多有用的思維。推薦給所有的軟體工程師。
在產品開發過程中，及早分享文檔初稿並從團隊成員那裡收集反饋是非常關鍵的。這樣做不僅可以在早期階段發現潛在的問題，而且還能讓團隊成員對文檔的發展有所貢獻，從而提高他們對最終產品的接受度。當文檔在創建過程中被共享，它成為了一個動態的工具，可以根據團隊的反饋進行調整和完善。
追求乾淨的程式碼是好的開始，但不要陷入過度設計的陷阱，導致程式難以維護。實際上，考慮團隊狀況和專注於解決真正的問題更為重要。了解公司的規模和現實情況，適時調整工作重心。技術不斷進步，使得寫程式變得更加容易，但這並不意味著工程師的角色會消失。在選擇技術時，也要考慮隱形成本有時簡單的解決方案反而更有效。
嚴格來說，不能算軟體開發分類，畢竟這篇比較像是通知文與心得文，但一定要選個分類，我就選之前常發的類別。
大意其實就只是我的技術文件之後不在 vocus 更新了，可以前往我用 docusaurus 架的網站上看新的技術文章。
「有時候，人們會嘲笑我們國家竟有這麼多過剩的書籍。可是，如果我還年輕有幹勁，我會選擇當編輯，從事出版事業。我們有責任讓智慧一直延續下去，絕對不可以把它當作炒熱門，卻罔顧良心的工作，因為那些粗製濫造的新書對於世界文學的危害程度，可能要遠大過戰爭帶來的後患。」～赫曼．赫塞
撰寫書評是個很好練習輸入、思考及輸出的做法。而撰寫書評的過程對於主題知識的積累，對於被看見其實有很大的幫助。擔任「樂寫網」書評作者的我，每個月都會幫PUBU電子書平台撰寫策略、創新及知識變現等相關書籍的書評，也開始有出版社行銷編輯的邀約，有機會推薦一些不錯的書籍。
嘿，大家新年快樂~ 新年大家都在做什麼呢？
跨年夜的我趕工製作某個外包設計案，在工作告一段落時趕上倒數。
然後和兩個小孩過了一個忙亂的元旦。在深夜時刻，看到朋友傳來的解籤網站，興致勃勃熬夜體驗了一下，覺得非常好玩，或許有人玩過了，但還是想寫上來分享紀錄一下~
這篇文章探討了工程師在如何有效提升自己，強調不僅僅是多coding，而是要對程式碼有更深層的理解。隨著職涯發展，工程師需要從單純的技術執行者轉變為團隊領導者，具備解決複雜問題和與他人有效溝通的能力。
改稿真的不是一件需要太多情緒的事，把錯的挑出來、改掉，就這麼簡單！很少有什麼「大錯」需要去爭執誰對誰錯。不過真的滿多時候鬼遮眼或是偶爾真的會發生某種「明明前一版是對的，這一版居然是錯的」的鬼故事，把問題找出來解決就好！
實際就業後，會發現收集與分析需求，通常都不是工程師在做，會有另一群人，以非工程的角度收集及分析需求，然後在開發過程中蹦出不同的火花，於是很好奇另一群人的想法是什麼？我不敢說這本書能完全代表另一群人的想法，但確實能夠得到很多有用的思維。推薦給所有的軟體工程師。
在產品開發過程中，及早分享文檔初稿並從團隊成員那裡收集反饋是非常關鍵的。這樣做不僅可以在早期階段發現潛在的問題，而且還能讓團隊成員對文檔的發展有所貢獻，從而提高他們對最終產品的接受度。當文檔在創建過程中被共享，它成為了一個動態的工具，可以根據團隊的反饋進行調整和完善。
追求乾淨的程式碼是好的開始，但不要陷入過度設計的陷阱，導致程式難以維護。實際上，考慮團隊狀況和專注於解決真正的問題更為重要。了解公司的規模和現實情況，適時調整工作重心。技術不斷進步，使得寫程式變得更加容易，但這並不意味著工程師的角色會消失。在選擇技術時，也要考慮隱形成本有時簡單的解決方案反而更有效。
嚴格來說，不能算軟體開發分類，畢竟這篇比較像是通知文與心得文，但一定要選個分類，我就選之前常發的類別。
大意其實就只是我的技術文件之後不在 vocus 更新了，可以前往我用 docusaurus 架的網站上看新的技術文章。
「有時候，人們會嘲笑我們國家竟有這麼多過剩的書籍。可是，如果我還年輕有幹勁，我會選擇當編輯，從事出版事業。我們有責任讓智慧一直延續下去，絕對不可以把它當作炒熱門，卻罔顧良心的工作，因為那些粗製濫造的新書對於世界文學的危害程度，可能要遠大過戰爭帶來的後患。」～赫曼．赫塞
撰寫書評是個很好練習輸入、思考及輸出的做法。而撰寫書評的過程對於主題知識的積累，對於被看見其實有很大的幫助。擔任「樂寫網」書評作者的我，每個月都會幫PUBU電子書平台撰寫策略、創新及知識變現等相關書籍的書評，也開始有出版社行銷編輯的邀約，有機會推薦一些不錯的書籍。