如何写好技术文档 - 排版格式和规范(一)
本文參考谷歌開發文檔風格指南、Vue官方文檔、React官方文檔、掘金小冊和阮一峰《中文技術文檔的寫作規范》，其中排版格式，主要參照Vue、React官網，寫作規范部分主要參考阮一峰老師的《中文技術文檔的寫作規范》。
編寫技術文檔除了排版格式和規范，思路和風格也極為重要，目前一些親和、幽默的寫作風格往往能獲得更多的閱讀量。
本文主要分為以下部分展開：
- 排版格式和規范
- 寫作思路
- 寫作風格
技術文檔通常使用markdown編寫，所以后面的內容都是針對Markdown文檔進行排版。
同時排版格式和寫作規范有很多重合部分，所以放在一篇文章說明。
文檔結構
以Vue、React官網為例，通常包含下面的文檔結構，如果要寫一個開源軟件的官方文檔，可以參考：
- 開始：包含簡介和快速上手
- 基礎：應用基礎使用
- 深入：進階說明
- API：API文檔
- FAQ：常見問題解答
- 參考：參考連接
標題
一篇文章主題應專一，如果出現多個主題，編寫多篇文章是更好的選擇，主題專一之后，對應的標題才會簡潔明了。
應避免標題層級過多，盡量少使用 3 級標題，最好不使用 4 級標題。
標題通常分為 4 級：
- 一級標題：通常不寫在文章內部，而是作為文章的標題顯示在固定的標題位置。
- 二級標題：文章內部主要使用的標題，類似Vue、React官方文檔中，絕大多數文章內只使用了二級標題。
- 三級標題：二級標題下的細分標題，一般在長文章中使用，中短篇文章如果標題設置合理，不需要使用。
- 四級標題：三級標題下的細分標題，不推薦使用，如果書寫文章時發現需要使用到四級標題，應查看你的每個二級標題是否屬于不同的主題，能否拆分為多篇文章。
下面是標題使用規范：
1.標題下應進行一些必要性簡述，不應該直接多層標題重疊。
示例：下面的一、二、三級標題直接放在一起。
結構一
# 一級標題
## 二級標題
### 三級標題
結構二
# 一級標題
這是一級標題的相關描述，可以是簡述下面二級大概包括的內容。
## 二級標題
這是二級標題的相關描述。
### 三級標題
2.一級標題下，不能直接出現三級標題，不要跨級使用標題。
示例：下面的文章結構，缺少二級標題。
# 一級標題
### 三級標題
3.標題要避免孤立編號（即同級標題只有一個）。
示例：下面的文章結構，二級標題 A只包含一個三級標題，完全可以省略三級標題 A。
## 二級標題 A
### 三級標題 A
## 二級標題 B
4.下級標題不重復上一級標題的名字。
示例：下面的文章結構，二級標題與下屬的三級標題同名，建議避免。
## 概述
### 概述
5.盡量少使用三級標題，不推薦使用四級標題，保持層級的簡單，防止出現過于復雜的章節。
如果三級標題下有并列性的內容，建議只使用項目列表來呈現。
示例：下面的結構二要好于結構一。結構一適用的場景，主要是較長篇幅的內容。
結構一
### 三級標題
#### 四級標題 A
#### 四級標題 B
結構二
### 三級標題
1. 四級標題A
2.四級標題B
正文
正文內包括句子、段落、圖片和列表等信息，推薦在這些內容之間使用換行，來達到更好的閱讀效果。
標點符號
標點符號通用使用規范：
- 中文語句的標點符號，均應該采取全角符號，這樣可以與全角文字保持視覺的一致。
- 如果整句為英文，則該句使用英文/半角標點。
- 句號、問號、嘆號、逗號、頓號、分號和冒號不得出現在一行之首。
- 點號（句號、逗號、頓號、分號、冒號）不得出現在標題的末尾，而標號（引號、括號、破折號、省略號、書名號、著重號、間隔號、嘆號、問號）可以。
1.句號使用規范
（1）中文語句的結尾處應該用全角句號（。）。
（2）句子末尾用括號加注時，句號應在括號之外。
錯誤：關于文件的輸出，請參照第 1.3 節（見第 26 頁。）
正確：關于文件的輸出，請參照第 1.3 節（見第 26 頁）。
2.逗號使用規范
（1）逗號（，）表示句子內部的一般性停頓。
注意避免“一逗到底”，即整個段落除了結尾，全部停頓都使用逗號。
3.頓號使用規范
（1）句子內部的并列詞，應該用全角頓號(、) 分隔，而不用逗號，即使并列詞是英語也是如此。
錯誤：我最欣賞的科技公司有 Google, Facebook, 騰訊, 阿里和百度等。
正確：我最欣賞的科技公司有 Google、Facebook、騰訊、阿里和百度等。
（2）英文句子中，并列詞語之間使用半角逗號（,）分隔。
例句：Microsoft Office includes Word, Excel, PowerPoint, Outlook and other components.
中文句子內部的并列詞，最后一個盡量使用（和）來連接，使句子讀起來更加連貫，下面兩個句子都可以，第二個更優。
正確：我最欣賞的科技公司有 Google、Facebook、騰訊、阿里，以及百度等。
正確：我最欣賞的科技公司有 Google、Facebook、騰訊、阿里和百度等。
4.分號使用規范
（1）分號（；）表示復句內部并列分句之間的停頓。
5.引號使用規范
引用時，應該使用全角雙引號（“ ”），注意前后雙引號不同。
例句：許多人都認為客戶服務的核心是“友好”和“專業”。
（2）引號里面還要用引號時，外面一層用雙引號，里面一層用單引號（‘ ’），注意前后單引號不同。
例句：鮑勃解釋道：“我要放音樂，可薩利說，‘不行！’。”
6.括號使用規范
（1）補充說明時，使用全角圓括號（（）），括號前后不加空格。
例句：請確認所有的連接（電纜和接插件）均安裝牢固。
幾種括號的中英文名稱。
| 英文 | 中文 | |
|---|---|---|
{ } |
braces 或 curly brackets | 大括號 |
[ ] |
square brackets 或 brackets | 方括號 |
< > |
angled brackets | 尖括號 |
( ) |
parentheses | 圓括號 |
7.冒號使用規范
（1）全角冒號（：）常用在需要解釋的詞語后邊，引出解釋和說明。
例句：請確認以下幾項內容：時間、地點、活動名稱和來賓數量。
（2）表示時間時，應使用半角冒號（:）。
例句：早上 8:00
8.省略號使用規范
（1）省略號（??）表示語句未完、或者語氣的不連續。
（2）省略號占兩個漢字空間、包含六個省略點，不要使用。。。或...等非標準形式。
（3）省略號不應與“等”這個詞一起使用。
錯誤：我們為會餐準備了香蕉、蘋果、梨…等各色水果。
正確：我們為會餐準備了各色水果，有香蕉、蘋果、梨??
正確：我們為會餐準備了香蕉、蘋果、梨等各色水果。
9.感嘆號使用規范
（1）應該使用平靜的語氣敘述，盡量避免使用感嘆號（！）。
（2）不得多個感嘆號連用，比如！！和!!!。
10.破折號使用規范
（1）破折號————一般用于進一步解釋。
（2）破折號應占兩個漢字的位置。如果破折號本身只占一個漢字的位置，那么前后應該留出一個半角空格。
例句：直覺————盡管它并不總是可靠的————告訴我，這事可能出了些問題。
例句：直覺 —— 盡管它并不總是可靠的 —— 告訴我，這事可能出了些問題。
11.連接號使用規范
（1）連接號用于連接兩個類似的詞。
（2）以下場合應該使用直線連接號（-），占一個半角字符的位置。
- 兩個名詞的復合
- 圖表編號
例句：氧化-還原反應
例句：圖 1-1
（3）數值范圍（例如日期、時間或數字）應該使用波浪連接號（～）或一字號（—），占一個全角字符的位置。
例句：2009 年～2011 年
注意，波浪連接號前后兩個值都建議加上單位。
（4）波浪連接號也可以用漢字“至”代替。
例句：周圍溫度：-20 °C 至 -10 °C
文本
markdown中文本排版直接從最左側開始即可，不用空兩個字。
下面是文本的使用規范：
1.少量使用文本加粗。
一定是非常重要的內容才使用加粗，隨意使用將導致整個文章顯示效果不佳，同時重點內容也不明顯。
2.全角中文字符與半角英文字符之間，應有一個半角空格。
錯誤：本文介紹如何快速啟動Windows系統。
正確：本文介紹如何快速啟動 Windows 系統。
3.全角中文字符與半角阿拉伯數字之間，有沒有半角空格都可，但必須保證風格統一，不能兩種風格混雜。
正確：2011年5月15日，我訂購了5臺筆記本電腦與10臺平板電腦。
正確：2011 年 5 月 15 日，我訂購了 5 臺筆記本電腦與 10 臺平板電腦。
半角的百分號，視同阿拉伯數字。
正確：今年我國經濟增長率是6.5%。
正確：今年我國經濟增長率是 6.5%。
4.英文單位若不翻譯，單位前的阿拉伯數字與單位符號之間，應留出適當的空隙。
例1：一部容量為 16 GB 的智能手機
例2：1 h = 60 min = 3,600 s
5.半角英文字符和半角阿拉伯數字，與全角標點符號之間不留空格。
錯誤：他的電腦是 MacBook Air 。
正確：他的電腦是 MacBook Air。
數值
1.阿拉伯數字一律使用半角形式，不得使用全角形式。
錯誤：這件商品的價格是１０００元。
正確：這件商品的價格是 1000 元。
2.數值為千位以上，應添加千分號（半角逗號）。
XXX 公司的實收資本為 ￥1,258,000 人民幣。
對于 4 位的數值，千分號是選用的，比如1000和1,000都可以接受。對于 4 位以上的數值，應添加千分號。
3.貨幣應為阿拉伯數字，并在數字前寫出貨幣符號，或在數字后寫出貨幣中文名稱。
$1,000
1,000 美元
4.表示數值范圍時，用波浪線（～）或一字線（—）連接。參見《標點符號》一節的“連接號”部分。
帶有單位或百分號時，兩個數字建議都要加上單位或百分號。
132 kg～234 kg
67%～89%
5.數字的增加要使用“增加了”、“增加到”。“了”表示增量，“到”表示定量。
增加到過去的兩倍
（過去為一，現在為二）
增加了兩倍
（過去為一，現在為三）
6.數字的減少要使用“降低了”、“降低到”。“了”表示增量，“到”表示定量。
降低到百分之八十
（定額是一百，現在是八十）
降低了百分之八十
（原來是一百，現在是二十）
不能用“降低 N 倍”或“減少 N 倍”的表示法，要用“降低百分之幾”或“減少百分之幾”。因為減少（或降低）一倍表示數值原來為一百，現在等于零。
句子
句子使用規范：
1.避免使用長句。
不包含任何標點符號的單個句子，或者以逗號分隔的句子構件，長度盡量保持在 20 個字以內；20～29 個字的句子，可以接受；30～39 個字的句子，語義必須明確，才能接受；多于 40 個字的句子，任何情況下都不能接受。
錯誤：本產品適用于從由一臺服務器進行動作控制的單一節點結構到由多臺服務器進行動作控制的并行處理程序結構等多種體系結構。
正確：本產品適用于多種體系結構。無論是由一臺服務器（單一節點結構），還是由多臺服務器（并行處理結構）進行動作控制，均可以使用本產品。
逗號分割的長句，總長度不應該超過 100 字或者正文的 3 行。
2.盡量使用簡單句和并列句，避免使用復合句。
并列句：他昨天生病了，沒有參加會議。
復合句：那個昨天生病的人沒有參加會議。
3.同樣一個意思，盡量使用肯定句表達，不使用否定句表達。
錯誤：請確認沒有接通裝置的電源。
正確：請確認裝置的電源已關閉。
4.避免使用雙重否定句。
錯誤：沒有刪除權限的用戶，不能刪除此文件。
正確：用戶必須擁有刪除權限，才能刪除此文件。
下面再看看英文的處理規范：
1.英文原文如果使用了復數形式，翻譯成中文時，應該將其還原為單數形式。
英文：...information stored in random access memory (RAMs)...
中文：??存儲在隨機存取存儲器（RAM）里的信息??
2.外文縮寫可以使用半角圓點(.)表示縮寫。
U.S.A.
Apple, Inc.
3.表示中文時，英文省略號（...）應改為中文省略號（??）。
英文：5 minutes later...
中文：5 分鐘過去了??
4.英文書名或電影名改用中文表達時，雙引號應改為書名號。
英文：He published an article entitled "The Future of the Aviation".
中文：他發表了一篇名為《航空業的未來》的文章。
5.第一次出現英文詞匯時，在括號中給出中文標注。此后再次出現時，直接使用英文縮寫即可。
IOC（International Olympic Committee，國際奧林匹克委員會）。這樣定義后，便可以直接使用“IOC”了。
6.專有名詞中每個詞第一個字母均應大寫，非專有名詞則不需要大寫。
“American Association of Physicists in Medicine”（美國醫學物理學家協會）是專有名詞，需要大寫。
“online transaction processing”（在線事務處理）不是專有名詞，不應大寫。
段落
下面是段落的寫作規范：
- 一個段落只能有一個主題，或一個中心句子。
- 段落的中心句子放在段首，對全段內容進行概述。后面陳述的句子為中心句子服務。
- 一個段落的長度不能超過七行，最佳段落長度小于等于四行。
- 段落的句子語氣要使用陳述和肯定語氣，避免使用感嘆語氣。
- 段落之間使用一個空行隔開。
- 段落開頭不要留出空白字符。
列表
列表包含無序列表和有序列表，推薦使用下面的規范：
1.必須是并列和遞進關系的內容，才使用列表。
絕大多數內容其實并不需要使用列表，查看React官方文檔，知識點基本使用了大量的正文進行描述，其中并沒有用小標題和列表進行分隔。
除非內容存在并列和遞進關系，并且僅僅是簡單羅列，才考慮使用列表，以Vue官方文檔為例，API文檔中，一個對象包含多個函數和屬性，它們是并列關系，但并不需要采用列表來表示，使用標題分隔是更佳的選擇。
當確定要使用列表時，注意并列關系時使用無序列表，遞進關系使用有序列表。
2.列表之間不要添加內容，緊密結合在一起展示。
列表應該盡可能直觀的排列在一起，如果列表之前需要添加內容，那么應該考慮將列表項換成標題。
本文前面內容就是一個反例，列表項之間添加了列表的一些描述，主要原因是本文是一個匯總式文章，每個列表項之間僅是簡單敘述，如果存在大量描述的話，應該使用標題來代替列表項名。
其它markdown內容
引用
因為markdown擁有的格式種類還是比較有限，所以引用標簽除了引用第三方內容外，通常還可以用于顯示一些提示、警告、總結等信息。
Vue和React官方不是單純的markdown格式，所以可以使用更豐富的css來顯示這部分內容。
如：
提示
這里是提示內容，和上面的提示最好隔一行。
下面是引用第三方內容時使用規范：
1.引用第三方內容時，應注明出處。
One man’s constant is another man’s variable. — Alan Perlis
2.如果是全篇轉載，請在全文開頭顯著位置注明作者和出處，并鏈接至原文。
本文轉載自 WikiQuote
3.使用外部圖片時，必須在圖片下方或文末標明來源。
本文部分圖片來自 Wikipedia
代碼
代碼包含句子中提及的關鍵詞代碼和大段的演示代碼。
1.句子中提及的代碼，應盡量少用代碼標簽包裹。
一個句子中可能提及很多代碼關鍵詞，但是只用 code 標簽包裹當前上下文關注的代碼關鍵詞是更好的選擇，高亮過多代碼關鍵詞整個句子看起來會雜亂。
2.代碼塊應盡量選擇正確的代碼語言，以高亮正確的關鍵字。
總結
以上是生活随笔為你收集整理的如何写好技术文档 - 排版格式和规范(一)的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 神经网络优化篇：理解mini-batch
- 下一篇： 面试官：请列举 Spring 的事务会失