閱讀|寫作|出版
Michael
2023-06-17|閱讀時間 ‧ 約 5 分鐘

Tom Johnson 的技術寫作經驗談

重點整理技術寫手 Tom Johnson 的兩段訪談。
這兩段訪談分別是：
底下是第一段訪談的重點概要。

關於 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!
（本文轉載自筆者部落格）
分享至
成為作者繼續創作的動力吧！
閱讀|寫作|出版
追蹤
閱讀|寫作|出版
追蹤
從 Google News 追蹤更多 vocus 的最新精選內容從 Google News 追蹤更多 vocus 的最新精選內容

閱讀|寫作|出版 的其他內容

你可能也想看

發表回應

成為會員 後即可發表留言
© 2024 vocus All rights reserved.