| 1 | # 文档体系
|
| 2 |
|
| 3 | ## 结构
|
| 4 |
|
| 5 | 软件手册是一部完整的书，建议采用下面的结构。
|
| 6 |
|
| 7 | - **简介**（Introduction）： [必备] [文件] 提供对产品和文档本身的总体的、扼要的说明
|
| 8 | - **快速上手**（Getting Started）：[可选] [文件] 如何最快速地使用产品
|
| 9 | - **入门篇**（Basics）： [必备] [目录] 又称”使用篇“，提供初级的使用教程
|
| 10 | - **环境准备**（Prerequisite）：[必备] [文件] 软件使用需要满足的前置条件
|
| 11 | - **安装**（Installation）：[可选] [文件] 软件的安装方法
|
| 12 | - **设置**（Configuration）：[必备] [文件] 软件的设置
|
| 13 | - **进阶篇**（Advanced)：[可选] [目录] 又称”开发篇“，提供中高级的开发教程
|
| 14 | - **API**（Reference）：[可选] [目录|文件] 软件 API 的逐一介绍
|
| 15 | - **FAQ**：[可选] [文件] 常见问题解答
|
| 16 | - **附录**（Appendix）：[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容
|
| 17 | - **Glossary**：[可选] [文件] 名词解释
|
| 18 | - **Recipes**：[可选] [文件] 最佳实践
|
| 19 | - **Troubleshooting**：[可选] [文件] 故障处理
|
| 20 | - **ChangeLog**：[可选] [文件] 版本说明
|
| 21 | - **Feedback**：[可选] [文件] 反馈方式
|
| 22 |
|
| 23 | 下面是两个真实范例，可参考。
|
| 24 |
|
| 25 | - [Redux 手册](http://redux.js.org)
|
| 26 | - [Atom 手册](http://flight-manual.atom.io)
|
| 27 |
|
| 28 | ## 文件名
|
| 29 |
|
| 30 | 文档的文件名不得含有空格。
|
| 31 |
|
| 32 | 文件名必须使用半角字符，不得使用全角字符。这也意味着，中文不能用于文件名。
|
| 33 |
|
| 34 | ```
|
| 35 | 错误： 名词解释.md
|
| 36 |
|
| 37 | 正确： glossary.md
|
| 38 | ```
|
| 39 |
|
| 40 | 文件名建议只使用小写字母，不使用大写字母。
|
| 41 |
|
| 42 | ```
|
| 43 | 错误：TroubleShooting.md
|
| 44 |
|
| 45 | 正确：troubleshooting.md
|
| 46 | ```
|
| 47 |
|
| 48 | 为了醒目，某些说明文件的文件名，可以使用大写字母，比如`README`、`LICENSE`。
|
| 49 |
|
| 50 | 文件名包含多个单词时，单词之间建议使用半角的连词线（`-`）分隔。
|
| 51 |
|
| 52 | ```
|
| 53 | 不佳：advanced_usage.md
|
| 54 |
|
| 55 | 正确：advanced-usage.md
|
| 56 | ``` |
| \ | No newline at end of file |