技術文檔寫作指南(1)

來源:阮一峰的 github

標題

層級

標題分四級。

  • 一級標題:文章的標題
  • 二級標題:文章主要部分的大標題
  • 三級標題:二級標題下面一級的小標題
  • 四級標題:三級標題下面某一方面的小標題

示例:

# 一級標題
## 二級標題
### 三級標題
#### 四級標題

原則


  1. 一級標題下,不能直接出現三級標題。
# 一級標題
### 三級標題
  1. 標題要避免孤立編號(即同級標題只有一個)。
## 二級標題 A 
### 三級標題 A
## 二級標題 B
  1. 下級標題不重復上一級標題的名字。
## 概述
### 概述
  1. 謹慎使用四級標題,盡量避免出現,保持層級的簡單,防止出現過于復雜的章節。`
結構一
### 三級標題
#### 四級標題 A
#### 四級標題 B
#### 四級標題 C

結構二
### 三級標題
**(1)A**
**(2)B**
**(3)C**

文本

字間距

全角中文字符與半角英文字符之間,應有一個半角空格。

錯誤:本文介紹如何快速啟動Windows系統。
正確:本文介紹如何快速啟動 Windows 系統。

全角中文字符與半角阿拉伯數字之間,有沒有半角空格都可,但必須保證風格統一,不能兩種風格混雜。

正確:2011年5月11日,我訂購了5臺筆記本電腦與10臺平板電腦。
正確:2011 年 5 月 15 日,我訂購了 5 臺筆記本電腦與 10 臺平板電腦。

半角的百分號,視同阿拉伯數字。
英文單位若不翻譯,單位前的阿拉伯數字與單位間不留空格。

錯誤:一部容量為 16 GB 的智能手機。
正確:一部容量為 16GB 的智能手機。

半角英文字符和半角阿拉伯數字,與全角標點符號之間不留空格。

錯誤:他的電腦是 MacBook Air 。
正確:他的電腦是 MacBook Air。

句子

  • 避免使用長句。句子內部不適用逗號時,總長度不應該超過 40 個字;使用逗號時,總長度不應該超過 100 字或者正文的 3 行。
  • 盡量使用簡單句和并列句,避免使用復合句。

寫作風格

  1. 盡量不適用被動語態,改為使用主動語態。
錯誤:假如此軟件尚未被安裝,
正確:假如尚未安裝這個軟件,
  1. 不適用非正式的語言風格。
錯誤:Lady Gaga 的演唱會真是酷斃了,從沒看過這么給力的表演!!!
正確:無法參加本次活動,我深感遺憾。
  1. 不適用冷僻、生造或者文言文的詞語,而要使用現代漢語的常用表達方式。
錯誤:這是唯二的快速啟動的方法。
正確:這是僅有的兩種快速啟動的方法。
  1. 用對“的”、“地”、“得”。
她露出了開心的笑容。
(形容詞 + 的 + 名詞)
她開心地笑了
(副詞 + 地 + 動詞)
她笑得很開心
(動詞 + 得 + 副詞)
  1. 使用代詞時(比如“其”、“該”,“此”,“這”等詞),必須明確指代的內容,保證只有一個含義。
錯誤:從管理系統可以監視中繼系統和受其直接控制的分配系統。
正確:從管理系統可以監視兩個系統:中繼系統和受中繼系統直接控制的分配系統。
  1. 名詞前不要使用過多的形容詞。
錯誤:此設備的使用必須在接受過本公司舉辦的正式的設備培訓的技師的指導下進行。
正確:此設備必須在技師的指導下使用,且指導技師必須接受過由本公司舉辦的正式設備培訓。
  1. 不包含任何標點符號的單個句子,或者以逗號分隔的句子構件,長度盡量保持在 20 個字以內;20~29 個字的句子,可以接受;30~39 個字的句子,語義必須明確,才能接受;多于 40個字的句子,在任何情況下都不能接受。
錯誤:本產品適用于從由一臺服務器進行動作控制的單一節點結構到由多臺服務器進行動作控制的并行處理程序結構等多種體系結構。
正確:本產品適用于多種體系結構。無論是由一臺服務器(單一節點結構),還是由多臺服務器(并行處理結構)進行動作控制,均可以使用本產品。
  1. 同樣一個意思,盡量使用肯定句表達,不使用否定句表達。
錯誤:請確認沒有接通裝置的電源。
正確:請確認裝置的電源已關閉。
  1. 避免使用雙重否定句。
錯誤:沒有刪除權限的用戶,不能刪除此文件。
正確:用戶必須擁有刪除權限,才能刪除此文件。

英文處理

英文原文如果使用了復數形式,翻譯成中文時,應將其還原為單數形式。

英文:···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”(在線事務處理)不是專用名詞,不應大寫。

3. 段落

原則

  • 一個段落只能有一個主題,或一個中心句子。
  • 段落的中心句子放在段首,對全段內容進行概述。后面陳述的句子為核心句服務。
  • 一個段落的長度不能超過七行,最佳段落長度小于等于四行。
  • 段落的句子預期要使用陳述和肯定語氣,避免使用感嘆語氣。
  • 段落之間使用一個空行隔開。
  • 段落開頭不要留出空白字符。

引用

引用第三方內容時,應注明出處。

One man's constant is another man's variable. -- Alan Perlis

如果是全篇轉載,請在全文開頭顯著位置注明作者和出處,并連接至原文。

本文轉自 WikiQuote

使用外部圖片時,必須在圖片下方或文末標明來源。

本文部分圖片來自 Wikipedia

下一篇:技術文檔寫作指南(2)

最后編輯于
?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明:文章內容(如有圖片或視頻亦包括在內)由作者上傳并發布,文章內容僅代表作者本人觀點,簡書系信息發布平臺,僅提供信息存儲服務。

推薦閱讀更多精彩內容

  • 優秀的公眾號,既要會做內容,還要懂的如何去編輯排版。 編輯排版就是要把文章打造成適合讀者的產品,用合適的方式,呈現...
    隨意寫意閱讀 3,168評論 0 1
  • 版權聲明:本文為 gfson 原創文章,轉載請注明出處。注:作者水平有限,文中如有不恰當之處,請予以指正,萬分感謝...
    gfson閱讀 1,197評論 0 0
  • CSS基礎 本文包括CSS基礎知識選擇器(重要!!!)繼承、特殊性、層疊、重要性CSS格式化排版單位和值盒模型浮動...
    廖少少閱讀 3,172評論 0 40
  • 五一歸來,我不想說眨眼間就到五月份了。 昨晚整理手機上的閱讀工具,尋求一個好的處理碎片化的工具。但是發現閱讀工具也...
    雙城記閱讀 214評論 0 1
  • 愛情啊! 你常常許諾能給人美麗的人生, 為什么你卻死無葬身之地? 愛情啊! 你常常夸耀你的魅力, 為什么觸摸過你的...
    文昭1閱讀 271評論 0 0