為什么要寫文檔?

　　你將會在 6 個月后使用你的代碼

　　我發現一開始從利己的角度來解釋這個問題會比較有吸引力。寫文檔最好的理由就是你將會在 6 個月后使用你的代碼。你 6 個月前寫的代碼跟別人寫的代碼對你來說通常沒有什么區別。你將會帶著一種熟悉的感覺讀你的代碼。然后一種不良的預兆悄悄逼近,你發現寫代碼的人毫無經驗,毫無智慧。

　　當你讀完幾個月前很簡單易懂或者取巧的代碼之后,你就會開始同情你的用戶。只要我寫下為什么我要這么做,生活就會變得如此簡單。文檔能讓你記錄代碼為什么這樣寫的原因。同樣地,代碼注釋解釋了為什么,而不是怎么做,文檔也是這樣。

　　你想要別人使用你的代碼

　　你已經寫了一段代碼,并且發布了它。你這樣做是因為你認為別人可能覺得它有用。但是,人們需要先知道為什么你的代碼對他們可能有用,才會決定使用它。文檔可以告訴人們這個項目對他們有用。

　　如果人們不知道你項目存在的意義,他們不會使用它。

　　如果人們不知道怎么安裝你的程序,他們不會使用它。

　　如果人們不知道怎么使用你的代碼,他們不會使用它。

　　只有少數人會深入研究你的代碼并且使用它。幾乎沒人會使用你的代碼,除非它有好的文檔。如果你真的熱愛你的項目,給它寫文檔,讓其他人使用它。

　　你需要別人的幫助

　　開源項目是具有魔力的,對嗎?你發布了代碼,然后 code gnomes 出現并且讓你的代碼更好。

　　當你發布代碼的時候會有一種奇妙的感覺產生。它通過各種方式出現,但總是能讓你興奮不已。有人在使用我的代碼?這是一種混合了恐懼和興奮的感覺。

　　我創造了價值!

　　如果它出錯了怎么辦?!

　　我是一個開源項目開發者了!

　　天哪,別人在使用我的代碼。。。

　　寫好的文檔能夠減輕這種恐懼。很多恐懼來自于給世界創造東西。我最喜歡的關于這個問題的引文如下所示:

　　恐懼來自于你做著重要的事情。

　　如果你在做不讓你恐懼的事情,那么它對你或者世界都沒有益處。

　　恭喜你感到恐懼!它意味著你在做重要的事情。

　　實際上,不完全是這樣。

　　開源項目確實令人感到驚奇,但它同樣必須符合現實世界的規則。你必須有付出,才有收獲。

　　在你為項目付出大量工作之后,才能獲得貢獻。

　　在你的項目有用戶之后,才能獲得貢獻。

　　在你的項目有文檔之后,才能獲得貢獻。

　　文檔也為你項目的第一次貢獻提供平臺。很多人從來沒有為開源項目貢獻過,讓他們修改代碼比修改文檔可怕得多。如果你沒有文檔,你將失去這類文檔貢獻者。

　　文檔讓你的代碼更好

　　有一個古老的事實:把東西寫下來幫助你更好地思考。頭腦里產生一個聽起來不錯的想法很容易,但是把想法寫到紙上就需要思想上的升華。

　　寫文檔能提升代碼的設計。在紙上討論你的API和設計決定可以讓你用一種更正式的方式思考它們。它還有一個不錯的副作用:讓別人按照你原來的意圖貢獻代碼。

　　你想成為一個更好的寫作者。

　　寫文檔跟大多數人體驗過的寫作方式不同。技術寫作是一種非與生俱來的藝術。寫文檔將會是你成為更好的技術寫作者這條路的起點,作為程序員,這是一個有用的技能。

　　寫作會隨著時間的流逝變得更容易。如果你好幾個月沒寫東西,再次動筆就會變得更加困難。邊做項目邊寫文檔將會讓你保持一個合理寫作節奏。

　　用什么工具寫作

　　簡單的開始是取得實際成果的最好方式。我將會提供一條平坦的路給你走,在你有了基本的想法之后,你可以擴大范圍。這些工具很強大并且容易使用。這將移除寫作的障礙。