為何要寫文件

UC Berkeley Library 的說法（理論代表）

<aside> 🦉 Documentation effectively connects humans and machines. 好文件可以教會人類與機器 溝通

</aside>

(Anna: machines / system / codes)

Why writing documentation

• For you
  • You will be using your code in 6 months
  • You want people to use your code and give you credit 讓自己的作品發揮功能與效益
  • You want to learn self-determination 自我實現
  • Others would be encouraged to contribute to your code 激勵他人站在自己的肩膀上（站在別人的肩膀上，也讓別人站在自己的肩膀上）
• For others
  • Others can easily use your code and build upon it 不要造成別人的痛苦
• For science
  • Advance the science
  • Encourage open science
  • Allow reproducibility and transparency

Library Guides: How to Write a Good Documentation: Home

Google 的說法（實務代表）

高質量的文件對於一個組織或團隊來說有非常多的益處，比如讓程式碼和API更容易理解、錯誤更少；讓團隊成員更專注於目標；也可以讓一些手工操作更容易；另外如果有新成員加入的話有文件也會讓他們更快融入……

寫文件有比較嚴重的收益滯後性，不像測試，你跑一個測試case，它能立即告訴你是對還是錯，它的價值馬上就體現出來了。而寫一份文件，隨著時間的推移，它的價值才會逐漸體現出來。 你可能只寫一次文件，將來它會被閱讀上百次、上千次，因為一份好的文件可以在未來替你向別人回答類似下面這些問題。

1. 為什麼當時是這麼決策的？
2. 為什麼程式碼是這樣實現的？
3. 這個專案裡都有哪些概念？

Anna 的說法

<aside> 🦉

文件通常用以表達個人對於一個問題或一個事件的解析，以及解決對應的方法。只有寫出答案，是不夠的，解題的過程讓智慧得以傳承。

</aside>

通用文件結構

從最簡單的開始：三段論法