from: http://www.cnblogs.com/cj723/archive/2012/03/15/2396422.html
上一篇文章我儘管表達了自己的一些想法，但卻有些觀點寫得不夠清楚，部分細節讓人誤解（比如對自信的理解）。所以，我決定重新寫一篇專門講如何寫技術文章的博文，來與大家交流我的寫作體會。本文適合有一定技術積累願意與他人分享技術心得的讀者。由於並未涉及具體技術，願意寫作的讀者均可以閱讀。
技術文章如何寫作能讓讀者有較好的閱讀體驗，是一個仁者見仁，智者見智的問題。甚至很多人都認爲根本不需要考慮讀者的感受，把技術寫好寫準確就可以了，這其實就是一大誤區，你的寫作如果只是給自己看，當然我也就不多說什麼，但如果你的寫作是給別人看，就一定要考慮如何寫的問題，因爲這是一個信息傳遞的過程而不是簡單的記錄。
事實上，對於一個準備開始寫作的人來說，通常是會認爲自己寫的東西一定是對的。如果一定要完全正確纔可以寫文章的話，那就會讓絕大多數人裹足不前。因此，寫得對不對雖然是作者應該首先要把握的，但是無論作者自己還是別人都無法在寫出文章公佈之前知道這一點，因此這不是我本文要談的重點。
我的核心觀點是： 好的技術文章，是讓符合閱讀條件的讀者，在良好閱讀體驗的情況下，看懂學會甚至掌握文章要傳達的信息。因此，需要寫作中不斷思考，這樣寫，讀者會有什麼感受。如果你的寫作不能讓讀者有一種收穫的喜悅，或者閱讀體驗不佳，那麼你的寫作就是有問題的。問題可能會有很多方面，我們一點點分析。
要告知讀者文章適合什麼人讀
首先要告知你寫的文章適合什麼人讀，這儘管不是最重要的條件，但你是打算一開始就告訴讀者，這文章的適讀人羣，還是讓讀者需要讀完文章後再自己去判斷這文章可不可以看得懂，兩者在閱讀體驗的感覺是完全不一樣的。通常一篇文章對於某個讀者不是太淺，就是太深。正好是自己不瞭解的技術知識，自己有興趣，而又能通過閱讀看得懂的文章纔是適合的好文章。因此由於讀者層次不同，你的文章給什麼人看的定位就很重要。
你把你的文章放到了博客園首頁上，那就意味着不管什麼層次的讀者都可能點擊進去。你如果不告知讀者，這個內容至少需要具備什麼樣的條件才能閱讀，對於一篇有一定技術難度的文章，初學者去閱讀它，怎麼可能高興得起來。
反之，如果你在一開頭就寫明，此文必須要有A、B、C的知識，否則還是不看爲妙，那麼誤入的讀者至少可以不需要繼續往下看，或者有個心理預期，可能看不懂，不過反正自己也沒到那個層次，沒什麼關係。
如果將寫作的具體技術難度分爲九級（九級最高），你打算寫一篇難度爲七級的文章。此時，你不應該考慮水平在一、二、三級的讀者，而是將四、五、六級的讀者作爲目標羣，因爲你的難度應該要讓讀者稍微費點力就夠得着的，而不是那種根本看不懂的人，這樣的定位纔會更有針對性。如果你寫的內容連二、三級讀者都能讀懂，那就說明實在是太囉嗦了，細節描述過多。如果只有七級水平的讀者才能看得懂，那通常又是因爲描述過於簡潔而忽視了細節。這兩種情況你的文章價值都會大大縮水。
清晰明白地指出文章適合什麼樣的人讀，這有很多方法。可以是標題、摘要或者文章開頭，只要達到提醒的作用，不要去浪費非目標讀者的時間就對了。
另外，如果可能，還應該在文章末尾提供繼續深入學習的建議，比如之後應該閱讀什麼書，看什麼文章等。也就是說，你可以爲你的讀者指明瞭接下來學習努力的方向。
總之，你在一開頭就告知此文章適合什麼人讀，幫助了讀者節約了判別的時間，這是一個非常好的開始。
寫作內容的難度層級遞進
不要一上來就是關鍵知識點，那雖然是一種風格，但卻違背了知識（或者說信息）傳遞的規律。
你在大街上看到了一漂亮姑娘，想讓她成爲自己的女朋友，你不能直接上去說“做我女朋友吧”，除非你開着法拉利或許可能。你首先要和她認識，並得到聯繫方式。簡單的辦法就是去搭訕。搭訕時如果直接說“給我你的手機號如何？”顯然也是不合適的，除非你長着貝克漢姆的臉興許可以。所以你得說點不讓人反感的話。比如：“你那iphone如果開啓手勢功能，就不需要頻繁按Home鍵了。不信？你看我的……”
舉技術寫作上的例子。在講算法時間複雜度的知識點時，你當然可以直接講時間複雜度的定義(就像大多數數據結構教材一樣)，可這是很讓讀者，特別是剛學的人迷惑的，爲什麼要強調這個呢？而且由於一上來就是對大O階推導，理解比較困難，讀者的體驗就相當差。
我在《大話數據結構》書中講解的辦法是先舉了從1加到100的算法例子，對比容易想到的算法和高斯算法的差異，來引入算法優劣間的差異，並詳細解釋了函數漸近增長的原理，最後再來給出時間複雜度的定義，以及推導大O階的方法。由於讀者理解了函數漸近增長的原理，再去理解時間複雜度就變得容易了，這就是層級遞進的作法。
運動員比賽前都需要熱身，男女親熱前也需要前戲。同樣，爲了讓讀者進入閱讀狀態，用一些簡單的例子來預熱，用一些稍難的例子來鋪墊，然後引出要講解的重點，這樣可以更好的達到講解好知識的目的。
得用讀者可以理解的語言，而不是你認爲好的語言
微博上有這樣一個段子。一位老太太想知道什麼是Facebook，約旦VC Ahmad Takatkah的解釋：
1)Facebook是一份報紙；
2)這報紙要在電腦或手機上看；
3)報紙裏只有家人和朋友的新聞，第2頁是兒子的、第3頁是妹妹的…
4)關於他們的新聞他們自己寫；
5)其中有一頁是你自己的，想寫什麼想讓誰看你說了算；
6)報紙第1頁，是全部內容摘要。
怎麼樣，是不是感覺很不錯？如果爲了讓老太太理解Facebook，去提什麼這是一家社交網站，它可以向親朋好友分享照片、視頻和個人信息等很IT化的語言，她一定是非常困惑。她可能接着就會問“什麼是社交網站”、“什麼是視頻”等問題了。
同樣，你如果想讓你的讀者閱讀體驗好，就一定要用適合他們的文字，而不是你自己喜歡的文字，哪怕你的文筆相當棒。
這一條可能是最重要的一點，信息的傳遞最終都是爲了讓讀者理解你的意圖。寫作時，一定要時刻想着用適合讀者的語言來表達。
一圖值千言
用上千個字描述不明白的東西，很可能一張圖就能解釋清楚。比如我在講解數據結構的歸併排序時，寫了很多文字來說明排序的原理，但如果沒有下面這樣一張圖，可能都是遺憾的。很多人也許就在看圖的一瞬間，就明白了前面的迷惑原來就是因爲大腦裏沒有這樣一個類似的數據變換概念造成的結果。
當然，也不一定要一張完整的大圖，也可以是多張小圖和相應的文字來解釋一個動態的過程。比如下面是進解二叉樹前序遍歷的部分截圖。通過文字加分解圖的方式，對於一個知識點的說明還是不錯的辦法。當然，最好的辦法是用動畫的形式來表現，目前暫時還不容易做到。或許未來的電子書，應用動靜結合的方式將會讓讀者有更加舒適的閱讀體驗。
不過你畢竟不是在畫漫畫，圖的目的是爲了更好的說明問題，如果只有圖，沒有抽象的文字來準確的表達你的意圖，可能就本末倒置了。
總之，在分析講解時，能夠通過一些圖形化的表達來說明問題一定會比純文字的表達更加容易理解。
代碼分解講解
時常看到這樣的情況，寫作者會把超過100行的大段代碼貼在博客中，然後在前或後面用一段的文字說明自己要分享的觀點，這是很難讓讀者感覺到愉悅的。因爲要認真讀懂你的代碼以及你文字表達的意思，讀者就必須要頻繁上下翻頁，這可是一件非常不爽的體驗過程。
解決辦法還是有的。不妨將大段的代碼分解成一個小函數一段說明文字，甚至是一句代碼一段說明文字的方式來講解。這樣的好處就是說明的文字就在代碼的旁邊，能夠很容易就查看到了。
另外，對於代碼的講解有時需要模擬其運行時的狀態，根據某一斷點時刻的變量變化情況描述來說明這個函數或這個循環是在幹什麼。這更加需要分解代碼來分析。
很明顯，本來是貼一段代碼，再寫一段文字就算是完事的工作，現在需要一段一段的說明，一定是更耗費精力和時間，但這是很值得的工作。這也是我在本文一再強調的是爲讀者考慮而非爲自己考慮的寫作方式。
多用章節條目段落
除非你的文章很短，不然我都建議儘量多分章節條目和段落。這樣讀者閱讀不會太累。
一些單機遊戲，比如極品飛車或實況足球等遊戲，一般一局的時間不會超過5分鐘。爲什麼要這樣設置，因爲這可以讓玩家精神集中一段時間之後得到一定的時間休息。
同樣，讀者讀的文字，如果幾千個字就組成一段話，那將是相當累的，多半情況就是閱讀不完就拉倒了。如果幾千個字分成六、七節，每一節各有四、五段，那就會好很多。讀者可以在每讀完一小節時，體會一下其內容，或者去上趟廁所。
即便是阿凡達這樣的極品大片，也是有尿點時間的，你的文章爲什麼不這麼做呢？
當然，章節條目最重要的作用是有利於幫助讀者瞭解整個文章的脈絡體系，更好的把握這篇文章講解的內容是什麼。
排版、背景顏色、字體顏色、大小、類型的處理
這些本身就是一門學問，都可以專門寫本書了。好的排版是沒有標準、也沒有止境的，可以做到千變萬化、賞心悅目。我非這方面特長，就不展開了。
不過，對於大多數讀者來說，比較傳統的排版就能夠取得比較好的閱讀效果，反而過於標新立異，比如黑底白字，藝術字體等方式是不可取的。
善待讀者
這個本不應該成爲一條，但還是覺得有必要提一下。你寫給自己看，把自己寫成上帝也沒人管你。可是你是寫給別人看的，你的目的不是打擊讀者，而是幫助讀者，那麼寫作中以及之後的回覆評論中，謙虛或與人爲善的態度纔是更值得提倡的。
人生來就是不公平的。有些人天生聰明，讀了最好的小學、中學、大學，工作在中國IT10強，甚至是世界IT10強的企業。他們自身可能也是非常努力，但由於他的一分努力總是抵得上別人兩分甚至五分的努力，加上只會越來越好人文環境和越來越多的技術資源，就算有點坎坷，最終成爲技術大牛幾乎就是必然。
一個願意分享技術心得的大牛相當難得，這一點一定要非常肯定。能讓大家佩服的原因，還是因爲他持續發表優秀文章的結果。但他們又時常會在表達正確技術觀點之時，順帶罵幾句犯錯誤的小菜鳥。這種自然而露的優越感總會讓一些暫時還學無所成的讀者垂頭喪氣。
我此前就說過，人都是從小長到大的，誰TM沒有幼稚過。當你成爲了技術牛人的時候，不應該忘記自己當年也是有過技術困惑，也是有過掙扎、努力、失敗的情況，體諒一下那些剛剛起步的小兄弟、理解一下他們的無知和淺薄爲什麼就不可以呢？他們中的有些人可能永遠也無法成爲技術牛人，但他們依然可以在自己的崗位上做出應有的貢獻。你的文章如果打擊了一些人，可能就真的傷害了他們，反之，如果可以幫助到其中的一些人，其實也是你對社會的貢獻，也是你的價值體現。
其實我也知道，我的這段文字改變不了大牛的態度，他們該怎麼寫還怎麼寫。只不過我覺得上天給了他們140分的智慧，他們卻只做到了120分的成績，實在是非常可惜。也就是說，我本覺得他們可以做得更加好。不信？翻看一下曾經的日記，是不是早已經忘記了當年那壯志豪情的理想了呢？
OK，重申一下我的觀點： 好的技術文章，是讓符合閱讀條件的讀者，在良好閱讀體驗的情況下，看懂學會甚至掌握文章要傳達的信息。我寫了一些注意的事項，都算不上新鮮內容，也未必全面，只能算是拋磚引玉。總的說來，如果你的寫作是爲了分享，那麼一定要時刻考慮你的讀者，有了這樣的心態，不愁寫不好技術文章。
注：對於一些如新聞類、搞笑類的博客不在此文指向的範圍內。本文只針對技術交流用的博客或者圖書的寫作。
