本文來(lái)自： ruanyf/document-style-guide

中文技術(shù)文檔的寫(xiě)作規(guī)范。

標(biāo)題

層級(jí)

標(biāo)題分為四級(jí)尉姨。

• 一級(jí)標(biāo)題：文章的標(biāo)題
• 二級(jí)標(biāo)題：文章主要部分的大標(biāo)題
• 三級(jí)標(biāo)題：二級(jí)標(biāo)題下面一級(jí)的小標(biāo)題
• 四級(jí)標(biāo)題：三級(jí)標(biāo)題下面某一方面的小標(biāo)題

下面是示例庵朝。

# 一級(jí)標(biāo)題

## 二級(jí)標(biāo)題

### 三級(jí)標(biāo)題

#### 四級(jí)標(biāo)題

原則

（1）一級(jí)標(biāo)題下，不能直接出現(xiàn)三級(jí)標(biāo)題又厉。

示例：下面的文章結(jié)構(gòu)偿短，缺少二級(jí)標(biāo)題。

# 一級(jí)標(biāo)題

### 三級(jí)標(biāo)題

（2）標(biāo)題要避免孤立編號(hào)（即同級(jí)標(biāo)題只有一個(gè)）馋没。

示例：下面的文章結(jié)構(gòu)昔逗，二級(jí)標(biāo)題 A只包含一個(gè)三級(jí)標(biāo)題，完全可以省略三級(jí)標(biāo)題 A篷朵。

## 二級(jí)標(biāo)題 A

### 三級(jí)標(biāo)題 A

## 二級(jí)標(biāo)題 B

（3）下級(jí)標(biāo)題不重復(fù)上一級(jí)標(biāo)題的名字勾怒。

示例：下面的文章結(jié)構(gòu)，二級(jí)標(biāo)題與下屬的三級(jí)標(biāo)題同名声旺，建議避免笔链。

## 概述

### 概述

（4）謹(jǐn)慎使用四級(jí)標(biāo)題，盡量避免出現(xiàn)腮猖，保持層級(jí)的簡(jiǎn)單鉴扫，防止出現(xiàn)過(guò)于復(fù)雜的章節(jié)。

如果三級(jí)標(biāo)題下有并列性的內(nèi)容澈缺，建議只使用項(xiàng)目列表（Item list）坪创。

示例：下面的結(jié)構(gòu)二要好于結(jié)構(gòu)一。后者適用的場(chǎng)景姐赡，主要是較長(zhǎng)篇幅的內(nèi)容莱预。

結(jié)構(gòu)一

### 三級(jí)標(biāo)題

#### 四級(jí)標(biāo)題 A

#### 四級(jí)標(biāo)題 B

#### 四級(jí)標(biāo)題 C

結(jié)構(gòu)二

### 三級(jí)標(biāo)題

**（1）A**

**（2）B**

**（3）C**

文本

字間距

全角中文字符與半角英文字符之間，應(yīng)有一個(gè)半角空格项滑。

錯(cuò)誤：本文介紹如何快速啟動(dòng)Windows系統(tǒng)依沮。

正確：本文介紹如何快速啟動(dòng) Windows 系統(tǒng)。

全角中文字符與半角阿拉伯?dāng)?shù)字之間，有沒(méi)有半角空格都可危喉，但必須保證風(fēng)格統(tǒng)一宋渔，不能兩種風(fēng)格混雜。

正確：2011年5月15日辜限，我訂購(gòu)了5臺(tái)筆記本電腦與10臺(tái)平板電腦傻谁。

正確：2011 年 5 月 15 日，我訂購(gòu)了 5 臺(tái)筆記本電腦與 10 臺(tái)平板電腦列粪。

半角的百分號(hào)审磁，視同阿拉伯?dāng)?shù)字。

英文單位若不翻譯岂座，單位前的阿拉伯?dāng)?shù)字與單位間不留空格态蒂。

錯(cuò)誤：一部容量為 16 GB 的智能手機(jī)

正確：一部容量為 16GB 的智能手機(jī)

半角英文字符和半角阿拉伯?dāng)?shù)字，與全角標(biāo)點(diǎn)符號(hào)之間不留空格费什。

錯(cuò)誤：他的電腦是 MacBook Air 钾恢。

正確：他的電腦是 MacBook Air。

句子

• 避免使用長(zhǎng)句鸳址。句子內(nèi)部不使用逗號(hào)時(shí)瘩蚪，總長(zhǎng)度不應(yīng)該超過(guò) 40 個(gè)字；使用逗號(hào)時(shí)稿黍，總長(zhǎng)度不應(yīng)該超過(guò) 100 字或者正文的 3 行疹瘦。
• 盡量使用簡(jiǎn)單句和并列句，避免使用復(fù)合句巡球。

寫(xiě)作風(fēng)格

1言沐、盡量不使用被動(dòng)語(yǔ)態(tài)，改為使用主動(dòng)語(yǔ)態(tài)酣栈。

錯(cuò)誤：假如此軟件尚未被安裝险胰，

正確：假如尚未安裝這個(gè)軟件，

2矿筝、不使用非正式的語(yǔ)言風(fēng)格起便。

錯(cuò)誤：Lady Gaga 的演唱會(huì)真是酷斃了，從沒(méi)看過(guò)這么給力的表演＝盐Ｓ茏邸！

正確：無(wú)法參加本次活動(dòng)陈辱，我深感遺憾奖年。

3、不使用冷僻沛贪、生造或者文言文的詞語(yǔ)，而要使用現(xiàn)代漢語(yǔ)的常用表達(dá)方式。

錯(cuò)誤：這是唯二的快速啟動(dòng)的方法利赋。

正確：這是僅有的兩種快速啟動(dòng)的方法水评。

4涮母、用對(duì)“的”匆浙、“地”、“得”缤沦。

她露出了開(kāi)心的笑容塘偎。
（形容詞＋的＋名詞）

她開(kāi)心地笑了疗涉。
（副詞＋地＋動(dòng)詞）

她笑得很開(kāi)心。
（動(dòng)詞＋得＋副詞）

5吟秩、使用代詞時(shí)（比如“其”咱扣、“該”、“此”涵防、“這”等詞）闹伪，必須明確指代的內(nèi)容，保證只有一個(gè)含義壮池。

錯(cuò)誤：從管理系統(tǒng)可以監(jiān)視中繼系統(tǒng)和受其直接控制的分配系統(tǒng)偏瓤。

正確：從管理系統(tǒng)可以監(jiān)視兩個(gè)系統(tǒng)：中繼系統(tǒng)和受中繼系統(tǒng)直接控制的分配系統(tǒng)。

6椰憋、名詞前不要使用過(guò)多的形容詞厅克。

錯(cuò)誤：此設(shè)備的使用必須在接受過(guò)本公司舉辦的正式的設(shè)備培訓(xùn)的技師的指導(dǎo)下進(jìn)行。

正確：此設(shè)備必須在技師的指導(dǎo)下使用橙依，且指導(dǎo)技師必須接受過(guò)由本公司舉辦的正式設(shè)備培訓(xùn)已骇。

7、不包含任何標(biāo)點(diǎn)符號(hào)的單個(gè)句子票编，或者以逗號(hào)分隔的句子構(gòu)件褪储，長(zhǎng)度盡量保持在 20 個(gè)字以?xún)?nèi)；20～29 個(gè)字的句子慧域，可以接受鲤竹；30～39 個(gè)字的句子，語(yǔ)義必須明確昔榴，才能接受辛藻；多于 40 個(gè)字的句子，在任何情況下都不能接受互订。

錯(cuò)誤：本產(chǎn)品適用于從由一臺(tái)服務(wù)器進(jìn)行動(dòng)作控制的單一節(jié)點(diǎn)結(jié)構(gòu)到由多臺(tái)服務(wù)器進(jìn)行動(dòng)作控制的并行處理程序結(jié)構(gòu)等多種體系結(jié)構(gòu)吱肌。

正確：本產(chǎn)品適用于多種體系結(jié)構(gòu)。無(wú)論是由一臺(tái)服務(wù)器（單一節(jié)點(diǎn)結(jié)構(gòu)）仰禽，還是由多臺(tái)服務(wù)器（并行處理結(jié)構(gòu)）進(jìn)行動(dòng)作控制氮墨，均可以使用本產(chǎn)品纺蛆。

8、同樣一個(gè)意思规揪，盡量使用肯定句表達(dá)桥氏，不使用否定句表達(dá)。

錯(cuò)誤：請(qǐng)確認(rèn)沒(méi)有接通裝置的電源猛铅。

正確：請(qǐng)確認(rèn)裝置的電源已關(guān)閉字支。

9、避免使用雙重否定句奸忽。

錯(cuò)誤：沒(méi)有刪除權(quán)限的用戶(hù)堕伪，不能刪除此文件。

正確：用戶(hù)必須擁有刪除權(quán)限栗菜，才能刪除此文件欠雌。

英文處理

英文原文如果使用了復(fù)數(shù)形式，翻譯成中文時(shí)苛萎，應(yīng)該將其還原為單數(shù)形式桨昙。

英文：?information stored in random access memory (RAMs)?

中文：……存儲(chǔ)在隨機(jī)存取存儲(chǔ)器（RAM）里的信息……

外文縮寫(xiě)可以使用半角圓點(diǎn)(.)表示縮寫(xiě)。

U.S.A.
Apple, Inc.

表示中文時(shí)腌歉，英文省略號(hào)（?）應(yīng)改為中文省略號(hào)（……）蛙酪。

英文：5 minutes later?

中文：5 分鐘過(guò)去了??

英文書(shū)名或電影名改用中文表達(dá)時(shí)，雙引號(hào)應(yīng)改為書(shū)名號(hào)翘盖。

英文：He published an article entitled "The Future of the Aviation".

中文：他發(fā)表了一篇名為《航空業(yè)的未來(lái)》的文章桂塞。

第一次出現(xiàn)英文詞匯時(shí)，在括號(hào)中給出中文標(biāo)注馍驯。此后再次出現(xiàn)時(shí)阁危，直接使用英文縮寫(xiě)即可。

IOC（International Olympic Committee汰瘫，國(guó)際奧林匹克委員會(huì)）狂打。這樣定義后，便可以直接使用“IOC”了混弥。

專(zhuān)有名詞中每個(gè)詞第一個(gè)字母均應(yīng)大寫(xiě)趴乡，非專(zhuān)有名詞則不需要大寫(xiě)。

“American Association of Physicists in Medicine”（美國(guó)醫(yī)學(xué)物理學(xué)家協(xié)會(huì)）是專(zhuān)有名詞蝗拿，需要大寫(xiě)晾捏。

“online transaction processing”（在線(xiàn)事務(wù)處理）不是專(zhuān)有名詞，不應(yīng)大寫(xiě)哀托。

段落

原則

• 一個(gè)段落只能有一個(gè)主題惦辛，或一個(gè)中心句子。
• 段落的中心句子放在段首仓手，對(duì)全段內(nèi)容進(jìn)行概述胖齐。后面陳述的句子為核心句服務(wù)玻淑。
• 一個(gè)段落的長(zhǎng)度不能超過(guò)七行，最佳段落長(zhǎng)度小于等于四行市怎。
• 段落的句子語(yǔ)氣要使用陳述和肯定語(yǔ)氣岁忘，避免使用感嘆語(yǔ)氣辛慰。
• 段落之間使用一個(gè)空行隔開(kāi)区匠。
• 段落開(kāi)頭不要留出空白字符。

引用

引用第三方內(nèi)容時(shí)帅腌，應(yīng)注明出處驰弄。

One man’s constant is another man’s variable. — Alan Perlis

如果是全篇轉(zhuǎn)載，請(qǐng)?jiān)谌拈_(kāi)頭顯著位置注明作者和出處速客，并鏈接至原文戚篙。

本文轉(zhuǎn)載自 WikiQuote

使用外部圖片時(shí)，必須在圖片下方或文末標(biāo)明來(lái)源溺职。

本文部分圖片來(lái)自 Wikipedia

數(shù)值

半角數(shù)字

數(shù)字一律使用半角形式岔擂，不得使用全角形式。

錯(cuò)誤： 這件商品的價(jià)格是１０００元浪耘。

正確： 這件商品的價(jià)格是 1000 元乱灵。

千分號(hào)

數(shù)值為千位以上，應(yīng)添加千分號(hào)（半角逗號(hào)）七冲。

XXX 公司的實(shí)收資本為 RMB1,258,000痛倚。

對(duì)于 4 ～ 6 位的數(shù)值，千分號(hào)是選用的澜躺，比如1000和1,000都可以接受蝉稳。對(duì)于7位及以上的數(shù)值，千分號(hào)是必須的掘鄙。

多位小數(shù)要從小數(shù)點(diǎn)后從左向右添加千分號(hào)耘戚，比如4.234,345。

貨幣

貨幣應(yīng)為阿拉伯?dāng)?shù)字操漠，并在數(shù)字前寫(xiě)出貨幣符號(hào)收津，或在數(shù)字后寫(xiě)出貨幣中文名稱(chēng)。

$1,000
1,000 美元

數(shù)值范圍

表示數(shù)值范圍時(shí)颅夺，用～連接朋截。參見(jiàn)《標(biāo)點(diǎn)符號(hào)》一節(jié)的“連接號(hào)”部分。

帶有單位或百分號(hào)時(shí)吧黄，兩個(gè)數(shù)字都要加上單位或百分號(hào)部服，不能只加后面一個(gè)。

錯(cuò)誤：132～234kg
正確：132kg～234kg

錯(cuò)誤：67～89%
正確：67%～89%

變化程度的表示法

數(shù)字的增加要使用“增加了”拗慨、“增加到”廓八》盥“了”表示增量，“到”表示定量剧蹂。

增加到過(guò)去的兩倍
（過(guò)去為一声功，現(xiàn)在為二）

增加了兩倍
（過(guò)去為一，現(xiàn)在為三）

數(shù)字的減少要使用“降低了”宠叼、“降低到”先巴。“了”表示增量冒冬，“到”表示定量伸蚯。

降低到百分之八十
（定額是一百，現(xiàn)在是八十）

降低了百分之八十
（原來(lái)是一百简烤，現(xiàn)在是二十）

不能用“降低N倍”或“減少N倍”的表示法剂邮，要用“降低百分之幾”或“減少百分之幾”。因?yàn)闇p少（或降低）一倍表示數(shù)值原來(lái)為一百横侦，現(xiàn)在等于零挥萌。

標(biāo)點(diǎn)符號(hào)

原則

• 中文語(yǔ)句的標(biāo)點(diǎn)符號(hào)，均應(yīng)該采取全角符號(hào)枉侧，這樣可以保證視覺(jué)的一致引瀑。
• 如果整句為英文，則該句使用英文/半角標(biāo)點(diǎn)棵逊。
• 句號(hào)伤疙、問(wèn)號(hào)、嘆號(hào)辆影、逗號(hào)徒像、頓號(hào)、分號(hào)和冒號(hào)不得出現(xiàn)在一行之首蛙讥。

句號(hào)

中文語(yǔ)句中的結(jié)尾處應(yīng)該用全角句號(hào)（锯蛀。）。

句子末尾用括號(hào)加注時(shí)次慢，句號(hào)應(yīng)在括號(hào)之外旁涤。

錯(cuò)誤：關(guān)于文件的輸出，請(qǐng)參照第 1.3 節(jié)（見(jiàn)第 26 頁(yè)迫像。）

正確：關(guān)于文件的輸出劈愚，請(qǐng)參照第 1.3 節(jié)（見(jiàn)第 26 頁(yè)）。

逗號(hào)

逗號(hào)闻妓，表示句子內(nèi)部的一般性停頓菌羽。

注意避免“一逗到底”，即整個(gè)段落除了結(jié)尾由缆，全部停頓都使用逗號(hào)注祖。

頓號(hào)

句子內(nèi)部的并列詞猾蒂，應(yīng)該用全角頓號(hào)(、) 分隔是晨，而不用逗號(hào)肚菠，即使并列詞是英語(yǔ)也是如此。

錯(cuò)誤：我最欣賞的科技公司有 Google, Facebook, 騰訊, 阿里和百度等罩缴。

正確：我最欣賞的科技公司有 Google蚊逢、Facebook、騰訊靴庆、阿里和百度等时捌。

英文句子中怒医，并列詞語(yǔ)之間使用半角逗號(hào)（,）分隔炉抒。

例句：Microsoft Office includes Word, Excel, PowerPoint, Outlook and other components.

分號(hào)

分號(hào)；表示復(fù)句內(nèi)部并列分句之間的停頓稚叹。

引號(hào)

引用時(shí)焰薄，應(yīng)該使用全角雙引號(hào)（“ ”），注意前后雙引號(hào)不同扒袖。

例句：許多人都認(rèn)為客戶(hù)服務(wù)的核心是“友好”和“專(zhuān)業(yè)”塞茅。

引號(hào)里面還要用引號(hào)時(shí)，外面一層用雙引號(hào)季率，里面一層用單引號(hào)（‘ ’）野瘦，注意前后單引號(hào)不同。

例句：鮑勃解釋道：“我要放音樂(lè)飒泻，可薩利說(shuō)鞭光，‘不行！’泞遗《栊恚”

圓括號(hào)

補(bǔ)充說(shuō)明時(shí)，使用全角圓括號(hào)（）史辙，括號(hào)前后不加空格汹买。

例句：請(qǐng)確認(rèn)所有的連接（電纜和接插件）均安裝牢固。

冒號(hào)

全角冒號(hào)（：）常用在需要解釋的詞語(yǔ)后邊聊倔，引出解釋和說(shuō)明晦毙。

例句：請(qǐng)確認(rèn)以下幾項(xiàng)內(nèi)容：時(shí)間、地點(diǎn)耙蔑、活動(dòng)名稱(chēng)见妒，以及來(lái)賓數(shù)量。

表示時(shí)間時(shí)纵潦，應(yīng)使用半角冒號(hào)（:）徐鹤。

例句：早上 8:00

省略號(hào)

省略號(hào)……表示語(yǔ)句未完垃环、或者語(yǔ)氣的不連續(xù)。它占兩個(gè)漢字空間返敬、包含六個(gè)省略點(diǎn)遂庄，不要使用。劲赠。涛目。或...等非標(biāo)準(zhǔn)形式。

省略號(hào)不應(yīng)與“等”這個(gè)詞一起使用凛澎。

錯(cuò)誤：我們?yōu)闀?huì)餐準(zhǔn)備了香蕉霹肝、蘋(píng)果、梨…等各色水果塑煎。

正確：我們?yōu)闀?huì)餐準(zhǔn)備了各色水果沫换，有香蕉、蘋(píng)果最铁、梨……

正確：我們?yōu)闀?huì)餐準(zhǔn)備了香蕉讯赏、蘋(píng)果、梨等各色水果冷尉。

感嘆號(hào)

應(yīng)該使用平靜的語(yǔ)氣敘述漱挎，盡量避免使用感嘆號(hào)！雀哨。

不得多個(gè)感嘆號(hào)連用磕谅，比如！雾棺！和!!!膊夹。

破折號(hào)

破折號(hào)————一般用于進(jìn)一步解釋。

破折號(hào)應(yīng)占兩個(gè)漢字的位置垢村。如果破折號(hào)本身只占一個(gè)漢字的位置割疾，那么前后應(yīng)該留出一個(gè)半角空格。

例句：直覺(jué)————盡管它并不總是可靠的————告訴我嘉栓，這事可能出了些問(wèn)題宏榕。

例句：直覺(jué) —— 盡管它并不總是可靠的 —— 告訴我，這事可能出了些問(wèn)題侵佃。

連接號(hào)

連接號(hào)用于連接兩個(gè)類(lèi)似的詞麻昼。

以下場(chǎng)合應(yīng)該使用直線(xiàn)連接號(hào)（-），占一個(gè)半角字符的位置馋辈。

• 兩個(gè)名詞的復(fù)合
• 圖表編號(hào)

例句：氧化-還原反應(yīng)

例句：圖 1-1

以下場(chǎng)合應(yīng)該使用波浪連接號(hào)（～）抚芦，占一個(gè)全角字符的位置。

• 數(shù)值范圍（例如日期、時(shí)間或數(shù)字）

例句：2009 年～2011 年

注意叉抡，波浪連接號(hào)前后兩個(gè)值都應(yīng)該加上單位尔崔。

波浪連接號(hào)也可以用漢字“至”代替。

例句：周?chē)鷾囟龋?20°C 至 -10°C

文檔體系

結(jié)構(gòu)

軟件手冊(cè)是一部完整的書(shū)褥民，建議采用下面的結(jié)構(gòu)季春。

• 簡(jiǎn)介（Introduction）： [必備] [文件] 提供對(duì)產(chǎn)品和文檔本身的總體的、扼要的說(shuō)明
• 快速上手（Getting Started）：[可選] [文件] 如何最快速地使用產(chǎn)品
• 入門(mén)篇（Basics）： [必備] [目錄](méi) 又稱(chēng)”使用篇“消返，提供初級(jí)的使用教程
  • 環(huán)境準(zhǔn)備（Prerequisite）：[必備] [文件] 軟件使用需要滿(mǎn)足的前置條件
  • 安裝（Installation）：[可選] [文件] 軟件的安裝方法
  • 設(shè)置（Configuration）：[必備] [文件] 軟件的設(shè)置
• 進(jìn)階篇（Advanced)：[可選] [目錄](méi) 又稱(chēng)”開(kāi)發(fā)篇“载弄，提供中高級(jí)的開(kāi)發(fā)教程
• API（Reference）：[可選] [目錄|文件] 軟件 API 的逐一介紹
• FAQ：[可選] [文件] 常見(jiàn)問(wèn)題解答
• 附錄（Appendix）：[可選] [目錄](méi) 不屬于教程本身、但對(duì)閱讀教程有幫助的內(nèi)容
  • Glossary：[可選] [文件] 名詞解釋
  • Recipes：[可選] [文件] 最佳實(shí)踐
  • Troubleshooting：[可選] [文件] 故障處理
  • ChangeLog：[可選] [文件] 版本說(shuō)明
  • Feedback：[可選] [文件] 反饋方式

下面是兩個(gè)真實(shí)范例撵颊，可參考宇攻。

• Redux 手冊(cè)
• Atom 手冊(cè)

文件名

文檔的文件名不得含有空格。

文件名必須使用半角字符倡勇，不得使用全角字符逞刷。這也意味著，中文不能用于文件名译隘。

錯(cuò)誤： 名詞解釋.md

正確： glossary.md

文件名建議只使用小寫(xiě)字母亲桥，不使用大寫(xiě)字母。

錯(cuò)誤：TroubleShooting.md

正確：troubleshooting.md 

為了醒目固耘，某些說(shuō)明文件的文件名，可以使用大寫(xiě)字母词身，比如README厅目、LICENSE。

文件名包含多個(gè)單詞時(shí)法严，單詞之間建議使用半角的連詞線(xiàn)（-）分隔损敷。

不佳：advanced_usage.md

正確：advanced-usage.md

參考鏈接

• 產(chǎn)品手冊(cè)中文寫(xiě)作規(guī)范, by 華為
• 寫(xiě)作規(guī)范和格式規(guī)范, by DaoCloud
• 技術(shù)寫(xiě)作技巧在日漢翻譯中的應(yīng)用, by 劉方
• 簡(jiǎn)體中文規(guī)范指南, by lengoo
• 文檔風(fēng)格指南, by LeanCloud
• 豌豆莢文案風(fēng)格指南, by 豌豆莢
• 中文文案排版指北, by sparanoid
• 中文排版需求, by W3C
• 為什么文件名要小寫(xiě)？, by 阮一峰
• Google Developer Documentation Style Guide, by Google