技術(shù)文檔規(guī)范 文檔體系

結(jié)構(gòu)

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

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

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

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

文件名

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

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

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


正確： glossary.md

文件名建議只使用小寫字母，不使用大寫字母。

錯(cuò)誤：TroubleShooting.md


正確：troubleshooting.md 

為了醒目，某些說明文件的文件名，可以使用大寫字母，比如README、LICENSE。

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

不佳：advanced_usage.md


正確：advanced-usage.md