Markdown技術文檔編寫規范

Markdown技術文檔編寫規范

Markdown是一種可以使用普通文本編輯器編寫的標記語言，通過簡單的標記語法，它可以使普通文本內容具有一定的格式。

---

文檔體系

• 結構

  • 簡介（Introduction）： [必備] [文件] 提供對產品和文檔本身的總體的、扼要的說明

  • 快速上手（Getting Started）：[可選] [文件] 如何最快速地使用產品

  • 入門篇（Basics）： [必備] [目錄] 又稱”使用篇“，提供初級的使用教程

    • 環境准備（Prerequisite）：[必備] [文件] 軟件使用需要滿足的前置條件
    • 安裝（Installation）：[可選] [文件] 軟件的安裝方法
    • 設置（Configuration）：[必備] [文件] 軟件的設置

  • 進階篇（Advanced)：[可選] [目錄] 又稱”開發篇“，提供中高級的開發教程

  • API（Reference）：[可選] [目錄|文件] 軟件 API 的逐一介紹

  • FAQ：[可選] [文件] 常見問題解答

  • 附錄（Appendix）：[可選] [目錄] 不屬於教程本身、但對閱讀教程有幫助的內容

    • Glossary：[可選] [文件] 名詞解釋
    • Recipes：[可選] [文件] 最佳實踐
    • Troubleshooting：[可選] [文件] 故障處理
    • ChangeLog：[可選] [文件] 版本說明
    • Feedback：[可選] [文件] 反饋方式

規則

• Markdown文檔文件后綴名使用 .md 。

• 文件名建議只使用小寫字母，多個單詞可使用 - 分隔。

  • 文件名不得含有空格。
  • 文件名不得使用全角字符（中文不能用於文件名）。
  • （為了醒目，某些說明文件的文件名，可以使用大寫字母，例如 README.md LICENSE.md文件。）

• 文件編碼統一使用 UTF-8 。

• 文章標題與內容之間必須有一個空行。

  // false
  ## 章節一
  內容
  ## 章節二
  
  // true
  ## 章節一
  
  內容
  
  ##章節二
  

• 代碼段必須使用如下風格：

···
// some code
// this is FCB(Fenced code blocks Style)
···

• 表格寫法應該參考如下風格：

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

| Left-Aligned  | Center Aligned  | Right Aligned |
| :------------ |:---------------:| -----:|
| col 3 is      | some wordy text | $1600 |
| col 2 is      | centered        |   $12 |
| zebra stripes | are neat        |    $1 |

• 中英文混排應該采用以下規則：

  • 英文和數字應使用半角字符
  • 中文文字之間不加空格
  • 中文文字與英文、阿拉伯數字及 @ # $ % ^ & * . ( ) 等符號之間加空格
  • 中文標點之間不加空格
  • 中文標點與前后字符（無論全角或半角）之間不加空格
  • 如果括號內有中文，則使用中文括號
  • 如果括號中的內容全部都是英文，則使用半角英文括號
  • 當半角符號 / 表示「或者」之意時，與前后的字符之間均不加空格

• 中文符號應該使用如下寫法

  • 用直角引號（「」）代替雙引號（“”）
  • 省略號使用「……」，而「。。。」僅用於表示停頓

• 表達方式（語法規范）：

  • 使段落成為文章的單元：一個段落只表達一個主題
  • 通常在每一段落開始要點題，在段落結尾要扣題
  • 使用主動語態
  • 陳述句中使用肯定說法
  • 刪除不必要的詞
  • 避免連續使用松散的句子
  • 使用相同的結構表達並列的意思
  • 將相關的詞放在一起
  • 在總結中，要用同一種時態（這里指英文中的時態，中文不適用，所以可以不理會）
  • 將強調的詞放在句末