背景

最近團(tuán)隊有同學(xué)提議，想探討如何才能寫出一篇優(yōu)秀的技術(shù)文章。所以盡管水平實(shí)在有限，還是按照自己的經(jīng)驗(yàn)和理解寫下了這篇文章，亞歷山大之余，也很高興和大家分享一下自己對技術(shù)寫作的一些思考。

希望本文可以拋磚引玉，大家從中可以有所思考和收獲，就能達(dá)到本文的目的了。那么，寫好一篇技術(shù)文章對我們有什么用呢？

我覺得有三點(diǎn)：

• 第一點(diǎn)，可以更好地分享傳播技術(shù)方案，讓讀者認(rèn)同贊賞你的文章；

• 第二點(diǎn)，通過文字表達(dá)提升個人的表達(dá)能力，在做技術(shù)分享和演講時提升效果及魅力；

• 第三點(diǎn)，通過整理技術(shù)文章，主動對技術(shù)深入思考剖析，提升個人的技術(shù)廣度和深度能力。

那么，接下來我重點(diǎn)分享下我實(shí)踐中的寫作流程。

寫作流程

寫作流程，大體上可以分為：寫作前的準(zhǔn)備工作、寫作中的注意事項和技巧以及寫作后的提升工作。

通過對這三個階段的打磨，相信你就可以寫出一篇“令人滿意”的技術(shù)文章。

寫作前

所謂萬事開頭難，所以寫作前的充分準(zhǔn)備工作，可以幫助你快速進(jìn)入寫作狀態(tài)，準(zhǔn)確明晰寫作內(nèi)容。讓我們通過以下手段，告別寫作開始時的“提筆皺眉”，體驗(yàn)一把“下筆如有神”。

確定立意標(biāo)題

我認(rèn)為立意和標(biāo)題應(yīng)該是先確定清楚的，要非常明確地知道自己要寫什么內(nèi)容，這個“什么”其實(shí)并沒有那么簡單確認(rèn)，可以參考以下羅列的確認(rèn)要素：

• 內(nèi)容傳達(dá)的目的是什么？

• 內(nèi)容關(guān)鍵字是什么？

• 內(nèi)容觸達(dá)的范圍是什么？

• 內(nèi)容的重點(diǎn)是什么？

最后，通過對立意的分析思考，形成一個立意明確的標(biāo)題。不要小看這個標(biāo)題，這個標(biāo)題是文章的“門面”，有時候甚至?xí)屪x者使用“一票否決權(quán)”。所以，標(biāo)題也應(yīng)該首先明確下來，在寫作中不斷圍繞立意的標(biāo)題進(jìn)行，這樣即不會產(chǎn)生跑題的情況，也對內(nèi)容進(jìn)行了充分強(qiáng)化。技術(shù)文章的標(biāo)題，其實(shí)不用起得那么“八卦”來吸引讀者，簡單直接即可。可以參考以下羅列的標(biāo)題要素：

• 緊扣內(nèi)容立意

• 簡短清晰

確認(rèn)目標(biāo)讀者

確認(rèn)目標(biāo)讀者是非常重要的，尤其文章需要在一些特殊場合中進(jìn)行發(fā)布和使用。是分享技術(shù)到社區(qū)？還是給領(lǐng)導(dǎo)匯報技術(shù)方案？還是具體下發(fā)開發(fā)執(zhí)行方案？不同的場景，寫作的側(cè)重點(diǎn)和用語都需要做相應(yīng)的調(diào)整。至于如何調(diào)整，這個需要對不同的環(huán)境進(jìn)行判斷，并不能一概而論，可以參考不同場景下要考慮的寫作要素：

• 文章中的稱謂

• 讀者最關(guān)心的是哪部分？過程？結(jié)果？還是數(shù)據(jù)？

• 是否需要為讀者提供某些補(bǔ)充資料？

形成樹形提綱

在確認(rèn)立意和目標(biāo)讀者之后，我們就可以開始“下筆”了，但是我建議不要急于寫文章的主體部分，而應(yīng)該先形成紙面的“樹形提綱”。當(dāng)然，如果寫作前腦子里的“布局”就已經(jīng)非常清晰，也可以省略紙面工作。其實(shí)，我們寫文章，尤其是比較長的文章，是應(yīng)該有目錄索引的，這樣非常方便讀者檢索。而這個步驟正好同時完成了目錄整理的過程：只需對樹形提綱進(jìn)行適當(dāng)提煉，就可以輕松成為我們的目錄索引了。可以參看本文的目錄索引，其實(shí)也就是本文的樹形提綱了。

準(zhǔn)備周邊素材

巧婦難為無米之炊，沒錯，提綱有了就相當(dāng)于鍋碗瓢勺等吃飯的架子都已準(zhǔn)備妥當(dāng)，就差最重要的“食材”就可以“做飯”（寫作）了。因?yàn)槲覀円呀?jīng)有了立意和樹形提綱，圍繞它們我們就可以明確知道接下來要寫什么內(nèi)容，那么拿什么來支撐內(nèi)容呢？可以參考以下可以準(zhǔn)備的素材分類：

• 關(guān)鍵概念

• 關(guān)鍵代碼

• 規(guī)范要求

• 案例支撐

• 圖片解釋

互動demo

其實(shí)周邊素材可以有很多，在前期準(zhǔn)備的時候可以“貪多”，最后再進(jìn)行“過濾”即可。而收集素材、審視素材的時候，會促進(jìn)我們來來回回地進(jìn)行學(xué)習(xí)和思考。這個過程對作者來說是十分有益的，不僅能把自己的經(jīng)驗(yàn)沉淀在紙面上，也同時在這個過程中不斷“驗(yàn)證”、“證偽”、“升華”自己的技術(shù)經(jīng)驗(yàn)，甚至碰撞出一些令人激動的“思維火花”。

調(diào)整樹形提綱

從樹形提綱形成之初，它就可以不斷進(jìn)行調(diào)整。不管在準(zhǔn)備周邊素材還是在寫作中或?qū)懽骱螅伎梢栽诋?dāng)下按照自己的理念進(jìn)行調(diào)整，或裁剪或豐滿。這有點(diǎn)兒像我們寫程序時，不斷調(diào)整參數(shù)以觀察不同的輸出結(jié)果，直到結(jié)果令人滿意，那么樹形提綱就“定型”了，與之關(guān)聯(lián)緊密的“目錄索引”也可輕松產(chǎn)出。這樣我們就可以有條不紊地開始寫作了。因?yàn)槲覀兪掷镉辛恕皹湫翁峋V”這個寫作向?qū)В筒挥迷贋椴恢缹懯裁矗恢朗遣皇桥茴}了而煩惱。

寫作中

我們順著“樹形提綱”有條不紊地進(jìn)行敘述就可以進(jìn)行文章主體部分的寫作了。但有的同學(xué)可能依然會感到困惑，還是不會寫怎么辦？其實(shí)這里我認(rèn)為涉及到一個寫作能力和技巧培養(yǎng)的問題。寫作能力的培養(yǎng)絕不是一朝一夕的事情，所以這里簡單地拋磚引玉，從寫作基本功、技術(shù)難點(diǎn)闡述以及提煉方法論這三個方面，簡單說下我對技術(shù)寫作的理解。

寫作基本功

寫作基本功其實(shí)是我們從識字開始就不斷練習(xí)的一種技能。我們平時讀文章，常常會感嘆有些作者的文筆很好。其實(shí)好的文筆一定是建立在良好的寫作基本功之上的。市面上有很多專門的書籍和課程來講怎么寫作，我們可以專門去學(xué)習(xí)這門“技藝”，當(dāng)然多看多練多模仿是少不了的，這里就不再展開這些內(nèi)容，主要列下需要注意的點(diǎn)：

• 格式：段落、標(biāo)點(diǎn)、字體、字號、數(shù)字等

• 語法：主謂賓、轉(zhuǎn)折、關(guān)聯(lián)等

• 段落：總分、層次、點(diǎn)題等

• 邏輯：清晰、自洽、完整、無歧義、用詞統(tǒng)一等

• 對仗：時間對仗、層次對仗、遞進(jìn)對仗等

技術(shù)闡述技巧

這里重點(diǎn)提一下技術(shù)方面的闡述技巧，因?yàn)槲覀儗懙氖抢浔拇a，它本身沒有過多的“人性”，而技術(shù)文章的使命就在于此，讓讀者不必“過深”地閱讀代碼，就可以從代碼那“百折千回”中領(lǐng)悟到你的“意圖”。一篇好的技術(shù)文章往往就是在這個環(huán)節(jié)做得非常出色，總是能讓讀者輕松領(lǐng)悟到代碼意圖，如果能讓讀者發(fā)出：“原來是這樣！cool！”如此的感嘆，那就是好的技術(shù)文章所帶來的魅力了。技術(shù)難點(diǎn)的闡述的難度往往是由技術(shù)本身的難度帶來的，因?yàn)椤盎逎y懂”的代碼轉(zhuǎn)化成“通俗易懂”的文字，是需要極強(qiáng)的技術(shù)能力和文字表達(dá)能力的。那么除了能力的培養(yǎng)提高之外，有沒有什么方法可以讓我們在寫技術(shù)難點(diǎn)時更有指導(dǎo)方向呢？下面我列舉了幾種方法，供大家參考。

舉例法

常用的手段之一就是舉例子，通過通俗的例子來解釋代碼邏輯。例如數(shù)據(jù)結(jié)構(gòu)queue（隊列）和stack（棧），我們就可以生活化地解釋它們。

queue：就是在排隊在“鮑師傅”窗口買蛋糕的隊伍，先來的人買完之后先離開，這對應(yīng)著queue中的值先進(jìn)先出的特性。

而stack：就是“老鷹抓小雞”中的隊伍，老鷹要從隊伍尾巴處把人一個一個抓出去，這對應(yīng)著stack中的值后進(jìn)先出的特性。

舉例子其實(shí)有很多手段，可以舉生活的例子，也可以舉復(fù)雜代碼簡化后的例子，還可以跨學(xué)科舉例子。只要有利于讀者通俗易懂并準(zhǔn)確get到核心的例子都是好例子。

重點(diǎn)突出法

很多時候，技術(shù)文章因?yàn)榧夹g(shù)點(diǎn)很多，而刪減技術(shù)點(diǎn)又不利于整體闡述。這時候，重點(diǎn)突出法非常管用。因?yàn)樵诿Ｃ５拇蟛菰凶寗e人發(fā)現(xiàn)一顆稀有的小草太難了，那我何不在這顆重要而稀有的小草旁邊立塊牌子，并寫上字“嘿！看過來，我在這！”呢。對于文章想要強(qiáng)調(diào)的重點(diǎn)，一定要重點(diǎn)突出出來，怎么可以突出呢？可以參考以下手段來突出重點(diǎn)：

• 相關(guān)重點(diǎn)給予足夠的篇幅

• 單獨(dú)成段

• 提煉小標(biāo)題

• 視覺加強(qiáng)：加粗、字體顏色、增加背景色等

圖像法

一圖勝千言，絕非虛言。讀者對圖的直接感知度往往要比干巴巴的文字要強(qiáng)很多。一張好的圖可以解釋大段文字才能說清楚的東西，甚至文字無法表達(dá)的“意境”同樣可以使用圖來“表意”。但是前提是圖是精心設(shè)計并準(zhǔn)確表意的，如果濫用圖或者圖使用不得當(dāng)則會適得其反。即使我們不知道畫什么，計算機(jī)領(lǐng)域里也依然有跡可循，由于圖強(qiáng)大的解釋力，軟件開發(fā)中層出不窮地建立了很多有關(guān)“圖”的規(guī)范：UML、流程圖、實(shí)體圖、數(shù)據(jù)流向圖、原型圖等等。善于利用這些圖會使得我們的“技術(shù)解釋力”更上一個臺階。

交互法

交互法和舉例法有些像，但是舉例法大多是“靜態(tài)”的，而交互法則更具生命力，它是可以“動態(tài)”交互的。例如我們在闡述多個實(shí)體的關(guān)聯(lián)關(guān)系的時候，我們可以提供給讀者一個交互動畫，讓讀者用連線的方式來理解實(shí)體間的關(guān)聯(lián)關(guān)系，這種讓讀者主動參與到技術(shù)學(xué)習(xí)中的方式，往往比被動地接受有用得多。交互法雖然制作成本大，但對于教學(xué)類的文章是效果非常好的闡述和演示工具。

提煉方法論

當(dāng)我們寫完文章主體部分后，寫一個讓人印象深刻的總結(jié)是非常有必要的。而這個總結(jié)得廣度和深度是可以發(fā)散的，也就是說可以從文章的點(diǎn)形成總結(jié)的面，從文章的面形成總結(jié)的體。從文章本身抽象到某個領(lǐng)域的通用規(guī)則，也就是提煉方法論。當(dāng)然，我非常不建議強(qiáng)行提煉，而當(dāng)這篇文章真的激發(fā)了你的深度思考并有所結(jié)論時，快，千萬別猶豫，把它總結(jié)提煉出來，這對于作者本人和讀者都將大有裨益。

寫作后

當(dāng)文章的主體寫作完畢，還是有一些方面需要繼續(xù)處理，這里重點(diǎn)討論三個方面。

通讀找錯

寫完文章，需要通讀文章，并在通讀的過程中尋找錯誤，例如錯別字、不通順語句、表意不明等。

查漏補(bǔ)缺

在通讀文章的過程中，繼續(xù)查漏補(bǔ)缺，多余的刪除，沒闡述完整或清晰的則需要增加。另外如果你的文章引用了規(guī)范、他人著作等，一定要加上引用說明，一來遵守被引用方的版權(quán)，二來為想要深入引用資料的讀者提供檢索便利。

升華立意

升華立意在技術(shù)文章中的確不多見，但是在某些特定場景下則可使文章更具“飽滿感”，例如把技術(shù)文章和公司戰(zhàn)略、技術(shù)前沿突破等方面結(jié)合起來，會使得技術(shù)文章同樣可以“發(fā)光發(fā)彩”和“走進(jìn)人心”。

結(jié)束語

其實(shí)如何寫好一篇技術(shù)文章這個問題的答案很簡單：技術(shù)好 + 寫作好。而本文著重闡述了我對如何“寫作好”的看法與總結(jié)。而這些大多都是“術(shù)”，想要達(dá)到更高境界，必須要悟“道”：培養(yǎng)自我獨(dú)有的感悟能力。

那么如何才能“悟道”呢？我也還在悟的路上，這里分享三個個人看法：

由于本人能力所限，請大家對本文不吝指正，望共同進(jìn)步。

后臺回復(fù)?學(xué)習(xí)資料?領(lǐng)取學(xué)習(xí)視頻