最近在找一些資料的時(shí)候，看的頭大，有很多很有技術(shù)含量的文章卻因?yàn)楦袷絾?wèn)題讓人開(kāi)頭就看不下去，實(shí)在可惜。這里就分享一下自己用 markdown 寫(xiě)文檔時(shí)的一些心得，希望能對(duì)大家有所幫助。
本文會(huì)從格式和內(nèi)容兩大方面出發(fā)，介紹一些能讓你文章更具表達(dá)性的小細(xì)節(jié)。
格式
1、不會(huì)使用空格和空行
合理使用空格和空行是 markdown 中最基礎(chǔ)也最重要的概念。咱們首先來(lái)聊聊空格，下面這條規(guī)則推薦每個(gè)人都記?。?/p>
中英文混排、中文數(shù)字混排時(shí)，數(shù)字和英文前后要插入空格。
例如下面兩個(gè)例子：
?? 看起來(lái)十分的擁擠
云函數(shù)又稱(chēng)函數(shù)即服務(wù)FaaS,它和后端即服務(wù)BaaS一起,都可以稱(chēng)為Serverless產(chǎn)品,云函數(shù)在2012年被首次提出。
?? 令人舒服的寫(xiě)法
云函數(shù)又稱(chēng)函數(shù)即服務(wù) FaaS，它和后端即服務(wù) BaaS 一起，都可以稱(chēng)為 Serverless 產(chǎn)品，云函數(shù)在 2012 年被首次提出。
和平時(shí)寫(xiě)代碼一樣，合理的使用空格會(huì)讓你的文章可讀性更高。
除了空格之外，md 中還有一個(gè)需要注意的點(diǎn)就是空行。在大多數(shù) markdown 解釋器中，單個(gè)換行是無(wú)效的，必須要空行（兩個(gè)換行符）之后才可以正確的換行。這就導(dǎo)致不了解這個(gè)特性的同學(xué)寫(xiě)出來(lái)的文檔變成了一個(gè)超長(zhǎng)大段落。
2、不會(huì)使用格式
在網(wǎng)上可以看到很多很長(zhǎng)一篇文章超長(zhǎng)段落，而且中間還一點(diǎn)格式都沒(méi)有，就像是一碗泡爛了的面一樣讓人難以下咽。下面介紹一下我平時(shí)是怎么使用常用格式的，主觀性較強(qiáng)，如果有異議的話(huà)歡迎評(píng)論區(qū)交流：
> 粗體
粗體 算是最常見(jiàn)的格式了，但是常見(jiàn)不代表可以大范圍使用，粗體是用來(lái)強(qiáng)調(diào)一段話(huà)，而強(qiáng)調(diào)必須有對(duì)比，所以不應(yīng)該頻繁使用。我比較推薦一個(gè)自然段中只出現(xiàn)一句粗體，如果沒(méi)有必要的話(huà)也可以不加，總之就 寧少勿多。
> 斜體
斜體 和粗體相反，代表一段話(huà)屬于次要內(nèi)容，所謂次要內(nèi)容就是指那些，就算是直接忽略掉也不會(huì)影響文章閱讀效果的內(nèi)容。
例如，寫(xiě)完一段后的引申內(nèi)容，或者有助于理解的解釋性?xún)?nèi)容，都可以用斜體標(biāo)注。
在英文文章中，也有使用斜體來(lái)表明內(nèi)容是引用或者其他語(yǔ)言的名詞。但是 markdown 中有專(zhuān)門(mén)的引用語(yǔ)法，并且漢語(yǔ)和外語(yǔ)差異也很大，不存在名詞混淆的情況。所以我一般都只在次要內(nèi)容上上使用斜體。
> 代碼塊
行內(nèi)代碼 就不多提了，這個(gè)能用錯(cuò)的人還是挺少的，這里重點(diǎn)提一下代碼塊：
就是這種代碼塊
很多人從來(lái)不用這種東西，而 markdown 不僅 ``` 是代碼塊，tab 和 4 空格縮進(jìn)也可以創(chuàng)建一個(gè)代碼塊，這就導(dǎo)致了一個(gè)讓人非常崩潰的問(wèn)題，如果你直接往 markdown 中貼一段代碼，就會(huì)變成下面這樣：
不知道你有沒(méi)有裂開(kāi)，反正我是裂開(kāi)了。markdown 發(fā)現(xiàn)你代碼中的縮進(jìn)，所以它會(huì)把這段文本中的一部分認(rèn)為是”代碼“，這不僅對(duì)閱讀沒(méi)有幫助，反而帶來(lái)了極佳的混淆效果。并且也可以看到，markdown 并不會(huì)顯示兩個(gè)以上的空格，所以文章里的代碼縮進(jìn)會(huì)直接消失。
所以作為程序員，你可以不用粗體不用斜體，但是一定要用代碼塊。
其實(shí)掌握了以上三種格式，已經(jīng)完全足夠我們寫(xiě)好一篇文檔了。你說(shuō)其他那些小格式有用么，當(dāng)然有用，但不常用，這里咱也不過(guò)多贅述了，下面才是重頭戲。
2、濫用格式
不要因?yàn)楹每炊褂媚硞€(gè)格式，比不會(huì)使用格式更糟糕的就是濫用格式，相信很多人都見(jiàn)過(guò)通篇粗體或者斜體的文章，粗體還好，通篇斜體真的是看的人眼都要瞎了。格式之所以有意義，是因?yàn)樗梢院推胀ㄎ谋井a(chǎn)生對(duì)比。通篇特殊字體等于沒(méi)有字體。
除了通篇用一個(gè)格式外，交雜使用過(guò)多不同格式也會(huì)降低閱讀體驗(yàn)，例如下面這段文字：
大多數(shù) Node.js 核心 API 構(gòu)建于慣用的 異步事件驅(qū)動(dòng)架構(gòu)，其中某些類(lèi)型的對(duì)象（又稱(chēng)觸發(fā)器，
Emitter）會(huì)觸發(fā)命名事件來(lái)調(diào)用函數(shù)（又稱(chēng)監(jiān)聽(tīng)器，Listener）。例如，
net.Server會(huì)在每次有新連接時(shí)觸發(fā)事件，fs.ReadStream會(huì)在打開(kāi)文件時(shí)觸發(fā)事件，stream會(huì)在數(shù)據(jù)可讀時(shí)觸發(fā)事件。所有能觸發(fā)事件的對(duì)象都是EventEmitter類(lèi)的實(shí)例。 這些對(duì)象有一個(gè)eventEmitter.on()函數(shù)，用于將一個(gè)或多個(gè)函數(shù)綁定到命名事件上。 事件的命名通常是 駝峰式的字符串，但也可以使用 任何有效的 JavaScript 屬性鍵。
要記住，特殊的文本格式會(huì)干擾你的閱讀速度，寫(xiě)文章和畫(huà)國(guó)畫(huà)一樣，要講究疏密有致。不要炫技一樣地在你的文章中添加各種格式讓內(nèi)容顯得花里胡哨。各種格式的內(nèi)容混雜在一起會(huì)弱化不同格式的意義。讓讀者花費(fèi)更多精力在分辨格式而不是內(nèi)容上（最后會(huì)讓讀者下意識(shí)的無(wú)視你的格式）。所以請(qǐng)記住以下兩點(diǎn)：
- 普通格式的內(nèi)容最好占全文的三分之二，最少不要低于一半。
- 盡量避免格式嵌套，比如一個(gè) 斜體中的 粗體。
3、根據(jù)自己的喜好選擇 header
很多 markdown 解釋器會(huì)使用 header（就是那些一級(jí)標(biāo)題、二級(jí)標(biāo)題等等）來(lái)自動(dòng)生成文章的目錄。所以應(yīng)盡量按照順序依次選擇標(biāo)題級(jí)別，而不是因?yàn)槟硞€(gè)標(biāo)題的大小自己不喜歡就跳級(jí)使用標(biāo)題。
內(nèi)容
1、過(guò)長(zhǎng)段落
文章讓人讀不下去的最大問(wèn)題就是過(guò)長(zhǎng)段落。如果一段文字越長(zhǎng)，認(rèn)真讀完的人也就越少。并且，一個(gè)段落中的內(nèi)容都是相互有所聯(lián)系的，所以絕大多數(shù)人都會(huì)選擇讀完一段文字之后再停下進(jìn)行思考或者進(jìn)行實(shí)踐，這也就導(dǎo)致了段落越長(zhǎng)，讀起來(lái)就會(huì)越累。
而且長(zhǎng)段落會(huì)下意識(shí)的給人一種 “這一段內(nèi)容難度比較大” 的感覺(jué)，讓人更不想去讀。你在各種官方技術(shù)棧的教程頁(yè)面都可以看到，幾乎沒(méi)有超過(guò)四行的段落，因?yàn)樵蕉痰亩温?，給人的感覺(jué)也就越簡(jiǎn)單。
想解決長(zhǎng)段落問(wèn)題也非常簡(jiǎn)單，如果有一個(gè)超長(zhǎng)段落，每隔兩三行找一個(gè)句號(hào)，然后換行就可以了。拆開(kāi)之后再加上兩句粗體，文章的整體風(fēng)格會(huì)立馬變得清爽并且層次分明起來(lái)。
組織文章段落的核心思想就是：保持合適且均勻的信息密度，如果一段內(nèi)容的信息密度太高，那么就應(yīng)該對(duì)其進(jìn)行拆分，如果幾段內(nèi)容的信息密度太低，那么就考慮是不是要合并段落，如果合并之后還是不夠（就是俗稱(chēng)：寫(xiě)的太水了），那么就要思考是不是重新精簡(jiǎn)一下語(yǔ)言了。
2、一筆帶過(guò)
寫(xiě)文章講究一個(gè)有理有據(jù)，然而很多人寫(xiě)技術(shù)文章都像是在寫(xiě)筆記一樣，點(diǎn)進(jìn)去一開(kāi)只有兩句話(huà)，第一句說(shuō)自己遇到了一個(gè)問(wèn)題，第二句說(shuō)執(zhí)行了一個(gè)命令就好了。當(dāng)你以為可以解決問(wèn)題并開(kāi)始實(shí)踐時(shí)，卻發(fā)現(xiàn)根本運(yùn)行不了或者缺少了一段關(guān)鍵代碼。你可能會(huì)選擇評(píng)論詢(xún)問(wèn)作者，但是遠(yuǎn)水解不了近渴，只好轉(zhuǎn)而尋找其他解決方法。過(guò)幾天作者看到了你的留言，然后告訴你應(yīng)該怎么做（也可能永遠(yuǎn)不會(huì)回復(fù)），然而解決問(wèn)題的你已經(jīng)不需要了。
真好，大家的時(shí)間都浪費(fèi)了，卻沒(méi)有什么作用。
這種”筆記“性質(zhì)的文章作者自己看了或許可以立刻想起來(lái)是怎么一回事（也有可能連自己都看不懂了，就像是寫(xiě)在備忘錄上的一串?dāng)?shù)字 ），但是對(duì)于不了解背景環(huán)境的讀者來(lái)說(shuō)就是一次令人難過(guò)的閱讀體驗(yàn)。
而現(xiàn)在站在作者的角度上，我認(rèn)為既然選擇了一個(gè)公開(kāi)的地方來(lái)分享自己的文章，那么至少應(yīng)該讓這篇文章可以自洽，而不是缺頭少尾的。這不僅讓讀者看起來(lái)可以更加省心，這節(jié)省了我們回復(fù)問(wèn)題的時(shí)間。下面是我總結(jié)的一些原則：
- 寫(xiě)明背景：在文章開(kāi)頭用簡(jiǎn)單幾句話(huà)說(shuō)明文章背景、使用的技術(shù)棧以及版本等。如果是系列文章的話(huà)一定要在開(kāi)頭帶上上一篇文章的鏈接。
- 寫(xiě)明參考：在文章最后注明參考，哪怕你自己寫(xiě)的很不詳細(xì)，讀者也可以通過(guò)你的參考來(lái)繼續(xù)深入下去，并且有參考鏈接也方便以后的自己查閱。
3、超長(zhǎng)代碼
如果你文章里出現(xiàn)了一段超過(guò)十行的代碼，那么就只會(huì)有不到一半的人認(rèn)真讀它。如果這段代碼還沒(méi)有注釋?zhuān)沁@些人還要再少一半。沒(méi)人喜歡讀代碼，無(wú)論是看文檔還是維護(hù)項(xiàng)目。所以如果你要貼一段代碼在文章里，一定記住要做下面兩件事：
- 添加注釋?zhuān)鸫a對(duì)你想讓讀者閱讀的（而不是直接拿去用）那部分代碼進(jìn)行注釋。
- 刪減無(wú)用的代碼，例如一個(gè)函數(shù)里邊只有中間一段代碼是你文章要講的，那么就刪掉上下不相干的代碼，然后寫(xiě)個(gè)注釋說(shuō)明這里進(jìn)行了刪減。
這個(gè)原則同樣適用于超長(zhǎng) log。特別是 github 的 Issue 區(qū)，經(jīng)常會(huì)出現(xiàn)鋪天蓋地的一大長(zhǎng)串 log，滾輪半天都滾不完。這一長(zhǎng)串有用么？絕大多數(shù)都是沒(méi)用的，那為什么不縮減一下呢，用不了幾秒鐘的朋友。
4、少用截圖
例如一些代碼段落、或者日志，能不用截圖就不用。
一是因?yàn)檫@種內(nèi)容 markdown 本身也有對(duì)應(yīng)格式可以顯示出來(lái)，并且比圖片加載快，小屏顯示效果也比圖片好。二是日后可能有復(fù)制需求，無(wú)論是你還是讀者，想要復(fù)制的時(shí)候卻發(fā)現(xiàn)這是一張圖片，那可真是要難受一下的。三是如果使用了一些外鏈圖片的話(huà)，圖床萬(wàn)一掛了就糟糕了，沒(méi)人會(huì)喜歡自己寫(xiě)的文章里有一張裂開(kāi)的圖片。
這一點(diǎn)不僅僅是截圖，其他能用非圖片形式說(shuō)明的，都不應(yīng)該添加配圖，除非添加了配圖之后能讓讀者更輕松的理解你的意圖，或者你明確的日后肯定沒(méi)有復(fù)制需求。這里要提一個(gè)特例，就是文章開(kāi)頭或者結(jié)束有時(shí)候會(huì)添加一張介紹圖片，特別是系列文章。就像下面這種：
我對(duì)這種配圖并不反對(duì)，畢竟讓讀者一眼就能看出來(lái)自己看的是什么相關(guān)的文章可是文字很難做到的?？偨Y(jié)起來(lái)就是一句話(huà)，能幫助讀者更好的理解和使用文章、而不是使絆子的配圖就是好配圖。
寫(xiě)在最后
上面列舉了不少很小但影響閱讀體驗(yàn)的地方，對(duì)于作者來(lái)說(shuō)其實(shí)要修改的并不多。就像是代碼規(guī)范一樣，制定規(guī)范對(duì)代碼的運(yùn)行影響不大，但可以讓閱讀和維護(hù)代碼的人更省心。
不過(guò)除了這些表面上的“樣式”，核心還是要看你的內(nèi)容是否有營(yíng)養(yǎng)。一篇知識(shí)濃度很高的文章，哪怕它的格式很爛，我也會(huì)覺(jué)得這是大佬不屑于顧及這些小細(xì)節(jié)；而如果文章都是從其他地方抄過(guò)來(lái)的，哪怕你格式再漂亮，我看了開(kāi)頭之后也會(huì)直呼上當(dāng)然后把他關(guān)掉。
下面的參考里列舉了一些 markdown 相關(guān)的規(guī)范文章，如果有興趣的話(huà)可以詳細(xì)了解下。ok，以上就是本文的全部?jī)?nèi)容，如有想法歡迎評(píng)論區(qū)交流。
