項目篇8講16丨你不愛寫

程序員確實很忙，但總有不那么忙的時候，卻也很少見有人利用這時間去寫文檔。包括我自己也這樣，有時候沒那么忙的時候，寧可去想想怎么重構下代碼，卻很少會愿意去寫文檔，主要還是太懶。對于這個問題，我其實反駁過多次，敏捷最后一句話明確：“盡管右項有其價值，我們更重視左項的價值。”也就是說敏捷從來沒有否認文檔的價值，只是更重視“工作的軟如果上手就寫代碼，就很容易陷入到某個技術細節(jié)中，而忽略了整體結構。寫的時候才發(fā)現(xiàn)一個技術難點無法解決，或者已經(jīng)在某個不重要的細節(jié)上浪費了很多時間；或是發(fā)現(xiàn)有些依賴其他人提供的服務還沒準備好；又或者是上線后才發(fā)現(xiàn)有安全。先寫文檔，就會拋開代碼細節(jié)，去站在全局思考。寫的時候，各個模塊之間的依賴關系、各種可能的安全隱患、各種可能需要其他人配合的地方，就都冒出來了，必須要去查資料，去找人討論，反復縝密的思考后最終寫出來。而這不是寫文檔的真正。真正的是沒想清楚，在心中只有一些未成型的的想法和概念，必須要努力把這些?！昂糜浶圆蝗鐮€筆頭”，存在腦子里的內(nèi)容是不可靠的，一個正常的項目組，如果需要長期，就需要一定的文檔，把設計、操作流程、環(huán)境配置等內(nèi)容記錄下來，而不僅僅依賴于口口相傳。我有一個習慣，每到一個新項目組，就會把日常工作中遇到的問題、各種環(huán)境配置、一些操作的步驟等，所有以后可能還會用上的都記錄下來，其中一些還會整理到團隊的WIKI上。一段時間后，這些隨手記下來內(nèi)容都會發(fā)揮大作用，對于我來說，很多問題就不需要問第二遍了。對于團隊來說，隨著人員更替，我記錄的這些內(nèi)容都是最好的一手資料，有新人過來，按照我當初記錄的內(nèi)容，就可以快速上手。比如說產(chǎn)品設計有雛型的時候，會有一個產(chǎn)品設計的評審會議，基于文檔，項目成員可以一起參與其中，提出自己的意見和看法。這樣就不至于等到產(chǎn)品設計出來之后，大家才對于設計有改進想法或意見，造成無法更改的結果。很多人對于寫文檔是有心理壓力，覺得自己寫作水平不高，不知道該如何下手。首先你要對文檔有一個正確的認識：文檔寫作，關鍵是通過文檔的想法表達出來，至于用詞、格式相對都是其次的。我們寫文檔就像是在家做飯，是不需要追求太多華麗的詞藻，也不需要追求字數(shù)，只要用簡單的文字、圖表把想法表達出來，最終在講解的時候，配合一些口頭說明就可以啦，其實比我們上學時寫作文容易多了。前面有提到，我其實一開始是不知道如何寫文檔的，直到畢業(yè)兩年后，我在飛信項目組，領導讓我寫一個新項目的技術方案文檔，我兩眼一抹黑說不會寫呀，然后給了我另一個項目的技術方案文檔，說你就“照葫蘆畫瓢”照著寫吧！后來我?guī)F隊時，讓團隊成員寫文檔，就把當時我寫的文檔給他們參考，很快他們也能寫了。包括后來我寫開源項目（angar-i-ree,reac-），要寫英文文檔，也是去找了幾個同類的開源項目的文檔，參照他們的內(nèi)容和格式，就把文檔拼出來了。有一次和同事一起去開會，會上他給另一個組的人介紹了如何調(diào)用一個服務，介紹的很詳細。我就建議他把剛才介紹的內(nèi)容寫成個小文檔，這樣下次再有類似會議就可以基于文檔來說。于是他就整理了一個簡單的文檔，再為別人講解的時候就基于文檔介紹，容易很多。同時，他每次還會再完善一點內(nèi)容進去。之后再有同類問題時，他直接把文檔發(fā)給人家就好了，都不需要再專門開會。步就是寫PPT，PPT有個好處就是不用太多文字，列個一二三，畫幾張圖，就是個簡單的文檔，PPT還有個好處就是可以用來給別人講解，收集反饋。寫完PPT，也收集好了反饋，再寫正式的文檔。先按照腦圖列的提綱把主要章節(jié)放上去，然后把PPT上的內(nèi)容和畫的圖放到文檔中，一篇文檔的骨架就搭好了，剩下的就是對細節(jié)一個原因是太難寫，要花很多時間精力，甚至可能寫不下去；另一個原因就是在收集反饋的過程中，會有很多修改。寫得越細則無用功越多，最后，你甚至會因為不想改文檔而抵觸不同的意見。而從粗到細逐步迭代的方式就好多了，一開始的目的是為了梳理清楚思路，只要腦圖這種級別的內(nèi)容就好了，然后進行調(diào)整。因為文檔很粗，調(diào)整也方便，等到基本確定后再寫細節(jié)，就不會有大的反復。Visio、、Keynote、OmniGraffle等都是很好的畫圖軟件。平時看到好的圖也例：當年的緩存方案（來源例：Netflix(來源：Netflix技術博客)流程圖是軟件項目文檔中一種常用圖形，可以方便的表示各種不同條件下的邏輯路徑。要畫好流程圖不難，重點是要理清楚邏輯關系，各個關鍵節(jié)點在不同條件下的。截圖也是個非常簡單直接的方式，把軟件的UI、交互設計的效果、數(shù)據(jù)趨勢圖、數(shù)據(jù)統(tǒng)計圖等直接截圖，必要的話配上一些箭頭、文字，也可以很好的說明清楚問題。尤其是產(chǎn)品設計文檔，經(jīng)常用到。上面就是如何寫文檔的一些具體建議，按照上面說的方法做，寫好項目文檔不會是多難的事Markdown是一種非常好的文檔格式，可以讓你更專注于內(nèi)容上，而不是文檔格式上面。沒時間寫或者懶，不能成為不寫文檔的理由。對于重要的項目文檔，就應該加入到日常的開發(fā)任務中，把寫文檔，擺在和設計、開發(fā)同等重要的位置。從某種角度來說，寫不好文檔，代碼也很難寫好。針對程序員不愛寫項目文檔的情況，我也提出了切實可行的寫文檔的方法。比如說不會寫，就可以從模仿別人寫的文檔開始，然后從粗到細，不斷迭代，配合一些圖表，就可以寫出不錯的項目文檔。 歸科技所有 不得售賣。頁面已增加防盜追蹤，將依法其上一 15|風險管理：不能盲目樂觀，凡事都應該有B計下一 17|需求分析到底要分析什么？怎么分析言言青 5 Redux: 2 2 曉偉呢。 1作者回復:謝謝邢愛 作者回復:我們2002年學軟件工程的時候，推薦的寫設計文檔就是你