- 本文不涉及具體的 Markdown 語法教學(xué)
本文主要介紹在使用 Markdown 語法來進(jìn)行技術(shù)文檔寫作時(shí)媳谁，如何選用合適的語法元素進(jìn)行排版涂滴，使得文檔具有清晰的邏輯、友好的可讀性以及美觀的形式晴音。
一柔纵、確定可用的語法元素
基本語法元素
頓號(hào)、逗號(hào)锤躁、句號(hào)搁料、破折號(hào)、引號(hào)、冒號(hào)郭计、括號(hào)霸琴、書名號(hào)、空格拣宏、換行通用的 Markdown 語法
標(biāo)題沈贝、段落杠人、區(qū)塊引用勋乾、代碼區(qū)塊、加粗嗡善、斜體辑莫、列表、分割線罩引、鏈接各吨、圖片、表格擴(kuò)展的 Markdown 語法
內(nèi)部鏈接袁铐、TOC 目錄揭蜒、腳注、刪除線剔桨、TODO 列表屉更、內(nèi)嵌 ICON、LaTex 語法支持洒缀、HTML 標(biāo)簽 等
注：表格其實(shí)是擴(kuò)展的 Markdown 語法瑰谜，放在通用語法是因?yàn)榛旧纤蓄A(yù)覽器都支持了表格，畢竟太重要了树绩。
注：內(nèi)部鏈接 和 TOC目錄 也是比較重要的語法萨脑，尤其是在篇幅比較大的文檔中，沒有文檔定位會(huì)帶來極大的閱讀障礙饺饭。
二渤早、分析文檔的組織結(jié)構(gòu)
- 確定文檔需要表達(dá)那些內(nèi)容
- 分析文檔不同內(nèi)容之間的聯(lián)系
文檔表達(dá)的是什么內(nèi)容，這些內(nèi)容之間有什么聯(lián)系瘫俊？可以通過哪些語言元素來表達(dá)這些元素蛛芥？下面從內(nèi)容的結(jié)構(gòu)屬性、內(nèi)容屬性军援、位置屬性三個(gè)方面進(jìn)行分析仅淑。
2.1 結(jié)構(gòu)屬性
層級(jí)結(jié)構(gòu)
B 是 A 的子概念、B 是對(duì) A 的說明等情況下文檔是層級(jí)結(jié)構(gòu)胸哥。
可用的語法元素：括號(hào)涯竟、父子列表、大小標(biāo)題、冒號(hào)
示例1.
- Object 類
- Fruit 類
- Apple 類
并行結(jié)構(gòu)
當(dāng)兩部分內(nèi)容是同一層次的概念庐船，或者從屬于同一話題银酬，或者是某種分類的結(jié)構(gòu)即為并行結(jié)構(gòu)。
可用的語法元素：頓號(hào)筐钟、逗號(hào)揩瞪、列表、表格篓冲、段落李破、標(biāo)題
示例1.
即時(shí)聊天系統(tǒng)
功能需求
技術(shù)方案
具體實(shí)現(xiàn)
示例2.
| 函數(shù)名 | 說明 | 備注 |
|---|---|---|
| io.open() | 打開文件 | 與 io.close() 成對(duì)使用 |
| io.close() | 關(guān)閉文件 | 與 io.open() 成對(duì)使用 |
關(guān)聯(lián)結(jié)構(gòu)
B是A的額外說明，B是A的同義表達(dá)壹将，B是A的進(jìn)一步說明嗤攻，這些結(jié)構(gòu)稱為關(guān)聯(lián)結(jié)構(gòu)。
可用的語法元素：分割線（分隔線沒有分隔開來的部分诽俯，說明是有關(guān)聯(lián)的內(nèi)容）妇菱、括號(hào)、冒號(hào)
示例1.
萬維網(wǎng)（World Wide Web暴区，亦作 “WWW”闯团、“Web”），是一個(gè)由許多互相鏈接的超文本組成的系統(tǒng)仙粱，通過互聯(lián)網(wǎng)訪問房交。
2.2 內(nèi)容屬性
簡短與冗長
根據(jù)一段文本占用篇幅來選擇語法元素。例如同樣是并行結(jié)構(gòu)缰盏，可以根據(jù)篇幅來確定是選用頓號(hào)還是選用列表涌萤，或者是選用段落。
示例1.
常用的編程語言有 C 語言口猜、Java 語言负溪、Python 語言等
示例2.
常用的語言：
- C語言，多用于偏向硬件層面的济炎，對(duì)性能要求高的項(xiàng)目
- Java 語言川抡，是世界上應(yīng)用最為廣泛的語言，在許多大型項(xiàng)目中使用
- Python 語言须尚，被譽(yù)為萬金油語言崖堤，學(xué)習(xí)門檻低，是每個(gè)人都值得學(xué)習(xí)的語言耐床。
示例3.
介紹一下目前比較流行的幾種語言的特點(diǎn)密幔、應(yīng)用領(lǐng)域和發(fā)展趨勢。
C 語言
Java 語言
Python 語言
重要與次要
對(duì)于重要的內(nèi)容撩轰，要選用強(qiáng)烈醒目的語法元素來吸引讀者的注意力胯甩。重要的內(nèi)容和次要的內(nèi)容在語法元素的選擇上要有所區(qū)分昧廷。
濫用醒目的元素會(huì)使讀者感到困擾，設(shè)想一下整篇文章都采用粗體的效果偎箫。
示例1.
執(zhí)行完 play 命令后木柬，請(qǐng)按任意鍵（電源鍵 ( i ) 除外！）退出淹办。
示例2.
本文檔未經(jīng)允許眉枕，不得轉(zhuǎn)載
如需轉(zhuǎn)載，請(qǐng)聯(lián)系 tangyikejun@163.com
2.3 位置屬性
對(duì)于臨近弱相關(guān)的內(nèi)容怜森，要想辦法把他們區(qū)分開來速挑。對(duì)于遙遠(yuǎn)但是有關(guān)聯(lián)的內(nèi)容，要想辦法把他們聯(lián)系起來塔插。
相關(guān)的語法元素：空格梗摇，換行拓哟，分隔符想许，內(nèi)部鏈接
其他技巧：序號(hào)，使用相同的語法元素
示例1.
if 語句
- ...
- ...
- ...
- ...
2.while 語句
3.for 語句
上面這個(gè)是一個(gè)反面教材断序，首先三者并不是并列關(guān)系流纹，用序號(hào)聯(lián)系在一起具有迷惑性。其次分割線把 while 語句 和 if 語句 分在一起违诗，而與 for 語句割裂開來了漱凝。更合適的做法是下面這樣
示例2.
條件語句
1.if 語句
- ...
- ...
- ...
- ...
循環(huán)語句
1.while 語句
2.for 語句
三、文檔迭代
牢記一點(diǎn)诸迟，文檔寫作是一個(gè)藝術(shù)加工的過程茸炒，不是一蹴而就的，是一個(gè)頻繁變更的過程阵苇，下面是在文檔寫作過程中需要注意的一些問題壁公。
- 評(píng)估內(nèi)容規(guī)模來選用相應(yīng)的語法元素
- 先用低層次的元素、內(nèi)容復(fù)雜化之后再使用高層次的
- 容易變動(dòng)的內(nèi)容最后再美化
- 借助版本控制獲取隨意刪改的自由
- 使用盡量少的語法元素
- 在同一個(gè)文檔中绅项，每種語法元素對(duì)應(yīng)一種明確的功能
