Technical writing for beginner
從 0 開始學習技術寫作 #1 - 給初學者的技術寫作
近期從產品經理轉職為 Technical Writer，為了加強自己的技術寫作能力，我決定將自己學習技術寫作的過程記錄下來。
關於 Technical Writing 的學習資源非常多，我研究了 Google Technical Writing, Gitlab Technical Writing 以及 Amazon 上的書籍。最終決定先從 WRITE THE DOCS 這個學習資源起手，它是目前我看到學習資源最豐富的網站。
這篇先從 《A beginner’s guide to writing documentation》開始。
1. 為什麼要寫技術文件 ?
主要有 5 個原因
(1) 6 個月後你還會使用到自己寫的程式碼
6 個月後我們會忘記當初為什麼寫下這段程式碼，寫文件是幫助未來的自己恢復記憶。
在紀錄文件的過程中，我們寫下了 why (為什麼) 這段程式碼要這樣作，幫助我們理清思緒。
為了讓自己在未來看得懂，我們間接的培養照顧讀者 (care your readers) 的心態。
(2) 你想要別人使用你的程式碼
身為開發者，我們想要其他人使用我們的程式碼，但前提是必須讓人理解「用你的程式碼有什麼好處」。 別人要如何使用你的程式碼呢？他們必須看得懂
這段程式碼可以達成什麼目的
如何安裝你的程式碼
了解與會使用你的程式碼
如果你愛護自己的專案，就需要寫清楚文件。
(3) 你想要別人幫助你
當我們成為 Open Source 軟體開發者時，總會希望有 contributor。
Contribute 只發生在 Open Source 有使用者、有文件、放了很多心力的情況下。
(4) 你想要讓程式碼寫的更好
寫文件能幫助自己設計程式。
例如在替 API 寫說明文件時，寫下自己為什麼要這樣設計，能幫助自己思考。
(5) 你想要成為一個更好的 writer
寫文件就是在做長期的寫作肌肉訓練，愈寫愈好、愈不寫愈難重新啟動。
2. 如何開始寫技術文件 ?
從簡單的步驟開始:
用列點寫大綱
從 README 開始
從使用 markup language (標記語言) 開始
慢慢培養寫作肌肉，養成寫文件的習慣。
3. 技術文件要寫給誰看?
從簡單開始，只需要先瞄準 2 種人:
User
Developer
前者只管如何使用 (how) 但不管程式碼如何運作;後者想要 contribute 因此需要了解 Code 的運作方式。
4. 文件要寫什麼 ?
寫以下內容:
一小段程式碼展示這個專案的功能
程式碼和 issue tracker 的連結
常見問題 (FAQ)
參考例子 Tastypie Cookbook
使用中碰到困難時如何取得協助
常見方式有 Mail, Community, IRC Channel, 通訊軟體 (Discord/ Slack...)。參考例子 FAQ: Getting Help | Django documentation
其他人如何 contribute
專案授權形式 (Project license)
可使用 Open Source Project license 快速查詢網站: Chooselicense
參考資源
A beginner’s guide to writing documentation
Last updated