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 |

• 中英文混排應該採用如下規則：

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

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

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

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

  • 使段落成爲文章的單元：一個段落只表達一個主題
  • 一般在每一段落開始要點題，在段落結尾要扣題
  • 使用主動語態
  • 陳述句中使用確定說法
  • 刪除沒必要要的詞
  • 避免連續使用鬆散的句子
  • 使用相同的結構表達並列的意思
  • 將相關的詞放在一塊兒
  • 在總結中，要用同一種時態（這裏指英文中的時態，中文不適用，因此能夠不理會）
  • 將強調的詞放在句末