技術文檔寫作規範(Markdown)

標題分為四級。 下面是示例。 （1）一級標題下，不克不及直接呈現三級標題。 示例：下面的文章構造，缺乏二級標題。 （2）標題要避免孤破編號（即同級標題只有一個）。 示例：下面的文章構造， 二級標題 A 只包含一個三級標題，完全可能省略 三級標題 A 。 （3）下級標題不重複上一級標題標名字。 示例：下面的文章構造，二級標題與下屬的三級標題同名，倡議避免。 （4）謹慎利用四級標題，盡管避免呈現，保持層級的簡單，避免呈現過於複雜的章節。 假如三級標題下有並列性的內容，倡議只利用項目列表（Item list）。 示例：下面的構造二要好於構造一。後者實用的場景，重如果較長篇幅的內容。 全形中文字元與半形英文字元之間，應有一個半形空格。 全形中文字元與半形阿拉伯數字之間，有不半形空格都可，但必須保證風格統一，不克不及兩種風格混淆。 半形的百分號，視同阿拉伯數字。 英文單位若不翻譯，單位前的阿拉伯數字與單位間不留空格。 半形英文字元跟半形阿拉伯數字，與全形標點標記之間不留空格。 1、盡管倒黴用主動語態，改為利用主動語態。 2、倒黴用非正式的言語風格。 3、倒黴用冷僻、生造或許白話文的詞語，而要利用現代漢語的常用表達方法。 4、用對「的」、「地」、「得」。 5、利用代詞時（比方「其」、「該」、「此」、「這」等詞），必須明白指代的內容，保證只有一個含義。 6、名詞前不要利用過多的描述詞。 7、不包含任何標點標記的單個句子，或許以逗號分開的句子構件，長度盡管保持在 20 個字以內；20～29 個字的句子，可能接收；30～39 個字的句子，語義必須明白，才幹接收；多於 40 個字的句子，在任何情況下都不克不及接收。 8、同樣一個意思，盡管利用斷定句表達，倒黴用否定句表達。 9、避免利用雙重否定句。 英文原文假如利用了複數情勢，翻譯成中文時，應當將其復原為雙數情勢。 外文縮寫可能利用半形圓點( . )表示縮寫。 表示中文時，英文省略號（ ⋯ ）應改為中文省略號（ …… ）。 英文書名或電影名改用中文表達時，雙引號應改為書名號。 第一次呈現英文辭彙時，在括弧中給出中文標註。此後再次呈現時，直接利用英文縮寫即可。 專有名詞中每個詞第一個字母均應大年夜寫，非專有名詞則不須要大年夜寫。 引用第三方內容時，應註明出處。 利用外部圖片時，必須在圖片下方或文末標明來源。 數字一律利用半形情勢，不得利用全形情勢。 數值為千位以上，應增加千分號（半形逗號）。 對 4 ～ 6 位的數值，千分號是選用的，比方 1000 跟 1,000 都可能接收。對7位及以上的數值，千分號是必須的。 多位小數要從小數點後從左向右增加千分號，比方 4.234,345 。 貨幣應為阿拉伯數字，並在數字前寫出貨幣標記，或在數字後寫出貨幣中文稱號。 表示數值範疇時，用 ～ 連接。拜見《標點標記》一節的「連接號」部分。 帶有單位或百分號時，兩個數字都要加上單位或百分號，不克不及只加前面一個。 數字的增加要利用「增加了」、「增加到」。「了」表示增量，「到」表示定量。 數字的增加要利用「降落了」、「降落到」。「了」表示增量，「到」表示定量。 不克不及用「降落N倍」或「增加N倍」的表示法，要用「降落百分之多少」或「增加百分之多少」。因為增加（或降落）一倍表示數值本來為一百，現在等於零。 中文語句中的開頭處應當用全形句號（ 。 ）。 句子末端用括弧加註時，句號應在括弧之外。 逗號 ， 表示句子外部的一般性停留。 注意避免「一逗究竟」，即全部段落除了卻尾，全部停留都利用逗號。 句子外部的並列詞，應當用全形頓號( 、 ) 分開，而不必逗號，即便並列詞是英語也是如此。 英詞句子中，並列詞語之間利用半形逗號（ , ）分開。 分號 ； 表示複句外部並列分句之間的停留。 引用時，應當利用全形雙引號（ 「 」 ），注意前後雙引號差別。 引號裡面還要用引號時，表面一層用雙引號，裡面一層用單引號（ 『 』 ），注意前後單引號差別。 補充闡明時，利用全形圓括弧 （） ，括弧前後不加空格。 全形冒號（ ： ）常用在須要闡明的詞語後邊，引出闡明跟闡明。 表示時光時，應利用半形冒號（ : ）。 省略號 …… 表示語句未完、或許語氣的不持續。它佔兩個漢字空間、包含六個省略點，不要利用 。。。 或 ... 等非標準情勢。 省略號不該與「等」這個詞一起利用。 應當利用安靜的語氣敘說，盡管避免利用感慨號 ！ 。 不得多個感慨號連用，比方 ！！ 跟 !!! 。 破折號 ———— 一般用於進一步闡明。 破折號應佔兩個漢字的地位。假如破折號本身只佔一個漢字的地位，那麼前後應當留出一個半形空格。 連接號用於連接兩個類似的詞。 以下場合應當利用直線連接號（ - ），佔一個半形字元的地位。 以下場合應當利用海浪連接號（ ～ ），佔一個全形字元的地位。 注意，海浪連接號前後兩個值都應當加上單位。 海浪連接號也可能用漢字「至」代替。 軟體手冊是一部完全的書，倡議採用下面的構造。 下面是兩個實在典範，可參考。 文檔的文件名不得含有空格。 文件名必須利用半形字元，不得利用全形字元。這也意味著，中文不克不及用於文件名。 文件名倡議只利用小寫字母，倒黴用大年夜寫字母。 為了奪目，某些闡明文件的文件名，可能利用大年夜寫字母，比方 README 、 LICENSE 。 文件名包含多個單詞時，單詞之間倡議利用半形的連詞線（ - ）分開。 檢查原文