最近公司項目的調用量突然漲了一大波，很多系統都紛紛扛不住了，於是需要對系統進行優化，系統優化的第一步，便是梳理業務！
在這個過程中，經常出現了這樣一些情況，發現數據庫的某些字段，沒有註釋，也沒有一定的文檔來詮釋它做什麼作用。而這個項目又是多達20，30人一起開發維護的，沒有人能夠從頭到尾說得清這個項目的主要流程。
寫文檔，似乎在國內的程序員，最不屑的一件事情了。作為一個程序員，有沒有必要寫技術文檔呢？
最近公司項目的調用量突然漲了一大波，很多系統都紛紛扛不住了，於是需要對系統進行優化，系統優化的第一步，便是梳理業務！
在這個過程中，經常出現了這樣一些情況，發現數據庫的某些字段，沒有註釋，也沒有一定的文檔來詮釋它做什麼作用。而這個項目又是多達20，30人一起開發維護的，沒有人能夠從頭到尾說得清這個項目的主要流程。
寫文檔，似乎在國內的程序員，最不屑的一件事情了。作為一個程序員，有沒有必要寫技術文檔呢？
要不要寫文檔
我們常說，Talk is cheap，show me your code。但是在實際的工作開發中，絕大部分情況，code才是最便宜的。工作的大部分時間，都是在進行業務的梳理，接口的溝通，剩下的，才是代碼的編寫與測試交付。
有些人會說，寫文檔是讓老闆跟容易找人替代你，也許現實生活中存在這樣的情況，但是一個人能否被替代，更多的是自己有沒有核心競爭力，每一個互聯網產品，都是有生命週期的，如果你的核心競爭力就是掌握了現有系統的坑，還不如提升自我，讓自己到哪都有飯吃！
也有人會說，寫文檔是寫給老闆們看的，對提升技術並沒有多大的作用。這句話知識說對了一般，最近，我們有一項重要的項目要對客戶與上面的老闆進行彙報，再一次感受到會說話的重要性，對一些不太懂技術的人說技術，是一門學問。寫代碼，終究只是人與機器交流，而寫文檔，是人與人之間的交流，大部分程序員，都不可一輩子在單打獨鬥地寫代碼，學會與人交流，決定了你的上限。
也有人說，只有大公司才寫文檔，小公司，做的都是一次性的項目，寫了文檔又有什麼用。寫文檔，其實並不是完全是寫給別人看，更多的是，讓你去進一步瞭解業務，瞭解技術，對業務進行梳理，站在一個更高的角度去思考整個系統。我有一個朋友，一開始只是一個外包公司的開發，但他非常擅於進行業務梳理，很快，他也自己出來開了一個外包公司，也過上奔小康的生活。
最近公司項目的調用量突然漲了一大波，很多系統都紛紛扛不住了，於是需要對系統進行優化，系統優化的第一步，便是梳理業務！
在這個過程中，經常出現了這樣一些情況，發現數據庫的某些字段，沒有註釋，也沒有一定的文檔來詮釋它做什麼作用。而這個項目又是多達20，30人一起開發維護的，沒有人能夠從頭到尾說得清這個項目的主要流程。
寫文檔，似乎在國內的程序員，最不屑的一件事情了。作為一個程序員，有沒有必要寫技術文檔呢？
要不要寫文檔
我們常說，Talk is cheap，show me your code。但是在實際的工作開發中，絕大部分情況，code才是最便宜的。工作的大部分時間，都是在進行業務的梳理，接口的溝通，剩下的，才是代碼的編寫與測試交付。
有些人會說，寫文檔是讓老闆跟容易找人替代你，也許現實生活中存在這樣的情況，但是一個人能否被替代，更多的是自己有沒有核心競爭力，每一個互聯網產品，都是有生命週期的，如果你的核心競爭力就是掌握了現有系統的坑，還不如提升自我，讓自己到哪都有飯吃！
也有人會說，寫文檔是寫給老闆們看的，對提升技術並沒有多大的作用。這句話知識說對了一般，最近，我們有一項重要的項目要對客戶與上面的老闆進行彙報，再一次感受到會說話的重要性，對一些不太懂技術的人說技術，是一門學問。寫代碼，終究只是人與機器交流，而寫文檔，是人與人之間的交流，大部分程序員，都不可一輩子在單打獨鬥地寫代碼，學會與人交流，決定了你的上限。
也有人說，只有大公司才寫文檔，小公司，做的都是一次性的項目，寫了文檔又有什麼用。寫文檔，其實並不是完全是寫給別人看，更多的是，讓你去進一步瞭解業務，瞭解技術，對業務進行梳理，站在一個更高的角度去思考整個系統。我有一個朋友，一開始只是一個外包公司的開發，但他非常擅於進行業務梳理，很快，他也自己出來開了一個外包公司，也過上奔小康的生活。
那麼，如何寫文檔才能避免寫流水賬呢？怎麼樣寫文檔才能讓所有的人都看懂。個人覺得，寫文檔最少要寫兩方面，一是總體設計，二是詳細的技術方案。
總體設計文檔
首先是需求與功能，用自然語言來描述這個系統要實現什麼功能，有什麼作用。經常有程序員想找掙外快的機會，可是連自己做的東西有什麼用都說不清的，真的很難去合作或者談到更高的價錢。
其次是架構與系統模塊。這個系統涉及到哪些功能模塊，每個模塊之間的調用關係是什麼樣，最好有一個簡單的架構圖。
最後是一些方案的對比，我們常常被教育著去尋找標準答案，但是這個世界更多的是合適的方案。多思考一下有沒有其他的方案，為什麼最終選擇這個方案，下次做到類似的需求，相信你會受益匪淺。
詳細設計
詳細設計，最重要的就是數據結構。這個功能主要有哪些數據，數據在計算機內部是以什麼形式進行存儲，表如何設計，這些都是至關重要。多年的寫代碼經驗告訴我，一個系統如果常出問題，無論是業務問題還是性能問題，絕大部分原因都是因為數據結構沒搞好。所以，在一些大型的公司，架構師的首要職責，便是梳理好基礎的數據結構。
系統調用時序圖，也就是交互流程，一個請求從一個系統流轉到另外一個系統，順序是什麼樣，各個系統又完成怎麼樣的責任，建議用時序圖進行表達。
性能指標與可拓展性，最後，如何跳出當前的業務去思考整個一個系統，當前的系統如何去應對將來的業務拓展，如果流量增加性能瓶頸又在哪裡。好的設計不是一蹴而就的，而是不停地進行思考和迭代。
最近公司項目的調用量突然漲了一大波，很多系統都紛紛扛不住了，於是需要對系統進行優化，系統優化的第一步，便是梳理業務！
在這個過程中，經常出現了這樣一些情況，發現數據庫的某些字段，沒有註釋，也沒有一定的文檔來詮釋它做什麼作用。而這個項目又是多達20，30人一起開發維護的，沒有人能夠從頭到尾說得清這個項目的主要流程。
寫文檔，似乎在國內的程序員，最不屑的一件事情了。作為一個程序員，有沒有必要寫技術文檔呢？
要不要寫文檔
我們常說，Talk is cheap，show me your code。但是在實際的工作開發中，絕大部分情況，code才是最便宜的。工作的大部分時間，都是在進行業務的梳理，接口的溝通，剩下的，才是代碼的編寫與測試交付。
有些人會說，寫文檔是讓老闆跟容易找人替代你，也許現實生活中存在這樣的情況，但是一個人能否被替代，更多的是自己有沒有核心競爭力，每一個互聯網產品，都是有生命週期的，如果你的核心競爭力就是掌握了現有系統的坑，還不如提升自我，讓自己到哪都有飯吃！
也有人會說，寫文檔是寫給老闆們看的，對提升技術並沒有多大的作用。這句話知識說對了一般，最近，我們有一項重要的項目要對客戶與上面的老闆進行彙報，再一次感受到會說話的重要性，對一些不太懂技術的人說技術，是一門學問。寫代碼，終究只是人與機器交流，而寫文檔，是人與人之間的交流，大部分程序員，都不可一輩子在單打獨鬥地寫代碼，學會與人交流，決定了你的上限。
也有人說，只有大公司才寫文檔，小公司，做的都是一次性的項目，寫了文檔又有什麼用。寫文檔，其實並不是完全是寫給別人看，更多的是，讓你去進一步瞭解業務，瞭解技術，對業務進行梳理，站在一個更高的角度去思考整個系統。我有一個朋友，一開始只是一個外包公司的開發，但他非常擅於進行業務梳理，很快，他也自己出來開了一個外包公司，也過上奔小康的生活。
那麼，如何寫文檔才能避免寫流水賬呢？怎麼樣寫文檔才能讓所有的人都看懂。個人覺得，寫文檔最少要寫兩方面，一是總體設計，二是詳細的技術方案。
總體設計文檔
首先是需求與功能，用自然語言來描述這個系統要實現什麼功能，有什麼作用。經常有程序員想找掙外快的機會，可是連自己做的東西有什麼用都說不清的，真的很難去合作或者談到更高的價錢。
其次是架構與系統模塊。這個系統涉及到哪些功能模塊，每個模塊之間的調用關係是什麼樣，最好有一個簡單的架構圖。
最後是一些方案的對比，我們常常被教育著去尋找標準答案，但是這個世界更多的是合適的方案。多思考一下有沒有其他的方案，為什麼最終選擇這個方案，下次做到類似的需求，相信你會受益匪淺。
詳細設計
詳細設計，最重要的就是數據結構。這個功能主要有哪些數據，數據在計算機內部是以什麼形式進行存儲，表如何設計，這些都是至關重要。多年的寫代碼經驗告訴我，一個系統如果常出問題，無論是業務問題還是性能問題，絕大部分原因都是因為數據結構沒搞好。所以，在一些大型的公司，架構師的首要職責，便是梳理好基礎的數據結構。
系統調用時序圖，也就是交互流程，一個請求從一個系統流轉到另外一個系統，順序是什麼樣，各個系統又完成怎麼樣的責任，建議用時序圖進行表達。
性能指標與可拓展性，最後，如何跳出當前的業務去思考整個一個系統，當前的系統如何去應對將來的業務拓展，如果流量增加性能瓶頸又在哪裡。好的設計不是一蹴而就的，而是不停地進行思考和迭代。
總結
程序員到底該不該寫技術文檔，相信你已經有答案。就好比蓋房子，即使不用設計圖，你也可以一邊搬磚一邊蓋樓，但是，如果你想蓋一個地標，一個摩天大樓，只有先有圖紙，才能預估好整個大樓的空間、承重、穩定性。另一方面來說，當你擁有了圖紙，擁有了畫圖的能力，蓋房子不就是找一群建築工的事情麼？寫代碼亦是如此。
好了，今天我們就介紹道這裡，歡迎大家關注我，整理後會和大家繼續分享。大家的支持是我繼續嘮嗑的動力。同名公眾號（沙茶敏碎碎念）