本文來自： ruanyf/document-style-guide
中文技術文檔的寫作規范。
標題
層級
標題分為四級。
- 一級標題：文章的標題
- 二級標題：文章主要部分的大標題
- 三級標題：二級標題下面一級的小標題
- 四級標題：三級標題下面某一方面的小標題
下面是示例。
# 一級標題
## 二級標題
### 三級標題
#### 四級標題
原則
（1）一級標題下，不能直接出現三級標題。
示例：下面的文章結構，缺少二級標題。
# 一級標題
### 三級標題
（2）標題要避免孤立編號（即同級標題只有一個）。
示例：下面的文章結構，二級標題 A只包含一個三級標題，完全可以省略三級標題 A。
## 二級標題 A
### 三級標題 A
## 二級標題 B
（3）下級標題不重復上一級標題的名字。
示例：下面的文章結構，二級標題與下屬的三級標題同名，建議避免。
## 概述
### 概述
（4）謹慎使用四級標題，盡量避免出現，保持層級的簡單，防止出現過于復雜的章節。
如果三級標題下有并列性的內容，建議只使用項目列表（Item list）。
示例：下面的結構二要好于結構一。后者適用的場景，主要是較長篇幅的內容。
結構一
### 三級標題
#### 四級標題 A
#### 四級標題 B
#### 四級標題 C
結構二
### 三級標題
**（1）A**
**（2）B**
**（3）C**
文本
字間距
全角中文字符與半角英文字符之間，應有一個半角空格。
錯誤：本文介紹如何快速啟動Windows系統。
正確：本文介紹如何快速啟動 Windows 系統。
全角中文字符與半角阿拉伯數字之間，有沒有半角空格都可，但必須保證風格統一，不能兩種風格混雜。
正確：2011年5月15日，我訂購了5臺筆記本電腦與10臺平板電腦。
正確：2011 年 5 月 15 日，我訂購了 5 臺筆記本電腦與 10 臺平板電腦。
半角的百分號，視同阿拉伯數字。
英文單位若不翻譯，單位前的阿拉伯數字與單位間不留空格。
錯誤：一部容量為 16 GB 的智能手機
正確：一部容量為 16GB 的智能手機
半角英文字符和半角阿拉伯數字，與全角標點符號之間不留空格。
錯誤：他的電腦是 MacBook Air 。
正確：他的電腦是 MacBook Air。
句子
- 避免使用長句。句子內部不使用逗號時，總長度不應該超過 40 個字；使用逗號時，總長度不應該超過 100 字或者正文的 3 行。
- 盡量使用簡單句和并列句，避免使用復合句。
寫作風格
1、盡量不使用被動語態，改為使用主動語態。
錯誤：假如此軟件尚未被安裝，
正確：假如尚未安裝這個軟件，
2、不使用非正式的語言風格。
錯誤：Lady Gaga 的演唱會真是酷斃了，從沒看過這么給力的表演！！！
正確：無法參加本次活動，我深感遺憾。
3、不使用冷僻、生造或者文言文的詞語，而要使用現代漢語的常用表達方式。
錯誤：這是唯二的快速啟動的方法。
正確：這是僅有的兩種快速啟動的方法。
4、用對“的”、“地”、“得”。
她露出了開心的笑容。
（形容詞＋的＋名詞）
她開心地笑了。
（副詞＋地＋動詞）
她笑得很開心。
（動詞＋得＋副詞）
5、使用代詞時（比如“其”、“該”、“此”、“這”等詞），必須明確指代的內容，保證只有一個含義。
錯誤：從管理系統可以監視中繼系統和受其直接控制的分配系統。
正確：從管理系統可以監視兩個系統：中繼系統和受中繼系統直接控制的分配系統。
6、名詞前不要使用過多的形容詞。
錯誤：此設備的使用必須在接受過本公司舉辦的正式的設備培訓的技師的指導下進行。
正確：此設備必須在技師的指導下使用，且指導技師必須接受過由本公司舉辦的正式設備培訓。
7、不包含任何標點符號的單個句子，或者以逗號分隔的句子構件，長度盡量保持在 20 個字以內；20～29 個字的句子，可以接受；30～39 個字的句子，語義必須明確，才能接受；多于 40 個字的句子，在任何情況下都不能接受。
錯誤：本產品適用于從由一臺服務器進行動作控制的單一節點結構到由多臺服務器進行動作控制的并行處理程序結構等多種體系結構。
正確：本產品適用于多種體系結構。無論是由一臺服務器（單一節點結構），還是由多臺服務器（并行處理結構）進行動作控制，均可以使用本產品。
8、同樣一個意思，盡量使用肯定句表達，不使用否定句表達。
錯誤：請確認沒有接通裝置的電源。
正確：請確認裝置的電源已關閉。
9、避免使用雙重否定句。
錯誤：沒有刪除權限的用戶，不能刪除此文件。
正確：用戶必須擁有刪除權限，才能刪除此文件。
英文處理
英文原文如果使用了復數形式，翻譯成中文時，應該將其還原為單數形式。
英文：?information stored in random access memory (RAMs)?
中文：……存儲在隨機存取存儲器（RAM）里的信息……
外文縮寫可以使用半角圓點(.)表示縮寫。
U.S.A.
Apple, Inc.
表示中文時，英文省略號（?）應改為中文省略號（……）。
英文：5 minutes later?
中文：5 分鐘過去了??
英文書名或電影名改用中文表達時，雙引號應改為書名號。
英文：He published an article entitled "The Future of the Aviation".
中文：他發表了一篇名為《航空業的未來》的文章。
第一次出現英文詞匯時，在括號中給出中文標注。此后再次出現時，直接使用英文縮寫即可。
IOC（International Olympic Committee，國際奧林匹克委員會）。這樣定義后，便可以直接使用“IOC”了。
專有名詞中每個詞第一個字母均應大寫，非專有名詞則不需要大寫。
“American Association of Physicists in Medicine”（美國醫學物理學家協會）是專有名詞，需要大寫。
“online transaction processing”（在線事務處理）不是專有名詞，不應大寫。
段落
原則
- 一個段落只能有一個主題，或一個中心句子。
- 段落的中心句子放在段首，對全段內容進行概述。后面陳述的句子為核心句服務。
- 一個段落的長度不能超過七行，最佳段落長度小于等于四行。
- 段落的句子語氣要使用陳述和肯定語氣，避免使用感嘆語氣。
- 段落之間使用一個空行隔開。
- 段落開頭不要留出空白字符。
引用
引用第三方內容時，應注明出處。
One man’s constant is another man’s variable. — Alan Perlis
如果是全篇轉載，請在全文開頭顯著位置注明作者和出處，并鏈接至原文。
本文轉載自 WikiQuote
使用外部圖片時，必須在圖片下方或文末標明來源。
本文部分圖片來自 Wikipedia
數值
半角數字
數字一律使用半角形式，不得使用全角形式。
錯誤： 這件商品的價格是１０００元。
正確： 這件商品的價格是 1000 元。
千分號
數值為千位以上，應添加千分號（半角逗號）。
XXX 公司的實收資本為 RMB1,258,000。
對于 4 ～ 6 位的數值，千分號是選用的，比如1000和1,000都可以接受。對于7位及以上的數值，千分號是必須的。
多位小數要從小數點后從左向右添加千分號，比如4.234,345。
貨幣
貨幣應為阿拉伯數字，并在數字前寫出貨幣符號，或在數字后寫出貨幣中文名稱。
$1,000
1,000 美元
數值范圍
表示數值范圍時，用～連接。參見《標點符號》一節的“連接號”部分。
帶有單位或百分號時，兩個數字都要加上單位或百分號，不能只加后面一個。
錯誤：132～234kg
正確：132kg～234kg
錯誤：67～89%
正確：67%～89%
變化程度的表示法
數字的增加要使用“增加了”、“增加到”。“了”表示增量，“到”表示定量。
增加到過去的兩倍
（過去為一，現在為二）
增加了兩倍
（過去為一，現在為三）
數字的減少要使用“降低了”、“降低到”。“了”表示增量，“到”表示定量。
降低到百分之八十
（定額是一百，現在是八十）
降低了百分之八十
（原來是一百，現在是二十）
不能用“降低N倍”或“減少N倍”的表示法，要用“降低百分之幾”或“減少百分之幾”。因為減少（或降低）一倍表示數值原來為一百，現在等于零。
標點符號
原則
- 中文語句的標點符號，均應該采取全角符號，這樣可以保證視覺的一致。
- 如果整句為英文，則該句使用英文/半角標點。
- 句號、問號、嘆號、逗號、頓號、分號和冒號不得出現在一行之首。
句號
中文語句中的結尾處應該用全角句號（。）。
句子末尾用括號加注時，句號應在括號之外。
錯誤：關于文件的輸出，請參照第 1.3 節（見第 26 頁。）
正確：關于文件的輸出，請參照第 1.3 節（見第 26 頁）。
逗號
逗號，表示句子內部的一般性停頓。
注意避免“一逗到底”，即整個段落除了結尾，全部停頓都使用逗號。
頓號
句子內部的并列詞，應該用全角頓號(、) 分隔，而不用逗號，即使并列詞是英語也是如此。
錯誤：我最欣賞的科技公司有 Google, Facebook, 騰訊, 阿里和百度等。
正確：我最欣賞的科技公司有 Google、Facebook、騰訊、阿里和百度等。
英文句子中，并列詞語之間使用半角逗號（,）分隔。
例句：Microsoft Office includes Word, Excel, PowerPoint, Outlook and other components.
分號
分號；表示復句內部并列分句之間的停頓。
引號
引用時，應該使用全角雙引號（“ ”），注意前后雙引號不同。
例句：許多人都認為客戶服務的核心是“友好”和“專業”。
引號里面還要用引號時，外面一層用雙引號，里面一層用單引號（‘ ’），注意前后單引號不同。
例句：鮑勃解釋道：“我要放音樂，可薩利說，‘不行！’。”
圓括號
補充說明時，使用全角圓括號（），括號前后不加空格。
例句：請確認所有的連接（電纜和接插件）均安裝牢固。
冒號
全角冒號（：）常用在需要解釋的詞語后邊，引出解釋和說明。
例句：請確認以下幾項內容：時間、地點、活動名稱，以及來賓數量。
表示時間時，應使用半角冒號（:）。
例句：早上 8:00
省略號
省略號……表示語句未完、或者語氣的不連續。它占兩個漢字空間、包含六個省略點，不要使用。。。或...等非標準形式。
省略號不應與“等”這個詞一起使用。
錯誤：我們為會餐準備了香蕉、蘋果、梨…等各色水果。
正確：我們為會餐準備了各色水果，有香蕉、蘋果、梨……
正確：我們為會餐準備了香蕉、蘋果、梨等各色水果。
感嘆號
應該使用平靜的語氣敘述，盡量避免使用感嘆號！。
不得多個感嘆號連用，比如！！和!!!。
破折號
破折號————一般用于進一步解釋。
破折號應占兩個漢字的位置。如果破折號本身只占一個漢字的位置，那么前后應該留出一個半角空格。
例句：直覺————盡管它并不總是可靠的————告訴我，這事可能出了些問題。
例句：直覺 —— 盡管它并不總是可靠的 —— 告訴我，這事可能出了些問題。
連接號
連接號用于連接兩個類似的詞。
以下場合應該使用直線連接號（-），占一個半角字符的位置。
- 兩個名詞的復合
- 圖表編號
例句：氧化-還原反應
例句：圖 1-1
以下場合應該使用波浪連接號（～），占一個全角字符的位置。
- 數值范圍（例如日期、時間或數字）
例句：2009 年～2011 年
注意，波浪連接號前后兩個值都應該加上單位。
波浪連接號也可以用漢字“至”代替。
例句：周圍溫度：-20°C 至 -10°C
文檔體系
結構
軟件手冊是一部完整的書，建議采用下面的結構。
- 簡介（Introduction）： [必備] [文件] 提供對產品和文檔本身的總體的、扼要的說明
- 快速上手（Getting Started）：[可選] [文件] 如何最快速地使用產品
-
入門篇（Basics）： [必備] [目錄] 又稱”使用篇“，提供初級的使用教程
- 環境準備（Prerequisite）：[必備] [文件] 軟件使用需要滿足的前置條件
- 安裝（Installation）：[可選] [文件] 軟件的安裝方法
- 設置（Configuration）：[必備] [文件] 軟件的設置
- 進階篇（Advanced)：[可選] [目錄] 又稱”開發篇“，提供中高級的開發教程
- API（Reference）：[可選] [目錄|文件] 軟件 API 的逐一介紹
- FAQ：[可選] [文件] 常見問題解答
-
附錄（Appendix）：[可選] [目錄] 不屬于教程本身、但對閱讀教程有幫助的內容
- Glossary：[可選] [文件] 名詞解釋
- Recipes：[可選] [文件] 最佳實踐
- Troubleshooting：[可選] [文件] 故障處理
- ChangeLog：[可選] [文件] 版本說明
- Feedback：[可選] [文件] 反饋方式
下面是兩個真實范例，可參考。
文件名
文檔的文件名不得含有空格。
文件名必須使用半角字符，不得使用全角字符。這也意味著，中文不能用于文件名。
錯誤： 名詞解釋.md
正確： glossary.md
文件名建議只使用小寫字母，不使用大寫字母。
錯誤：TroubleShooting.md
正確：troubleshooting.md
為了醒目，某些說明文件的文件名，可以使用大寫字母，比如README、LICENSE。
文件名包含多個單詞時，單詞之間建議使用半角的連詞線（-）分隔。
不佳：advanced_usage.md
正確：advanced-usage.md
參考鏈接
- 產品手冊中文寫作規范, by 華為
- 寫作規范和格式規范, by DaoCloud
- 技術寫作技巧在日漢翻譯中的應用, by 劉方
- 簡體中文規范指南, by lengoo
- 文檔風格指南, by LeanCloud
- 豌豆莢文案風格指南, by 豌豆莢
- 中文文案排版指北, by sparanoid
- 中文排版需求, by W3C
- 為什么文件名要小寫？, by 阮一峰
- Google Developer Documentation Style Guide, by Google
