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