Markdown技术文档编写规范
Markdown技术文档编写规范
Markdown是一种可以使用普通文本编辑器编写的标记语言，通过简单的标记语法，它可以使普通文本内容具有一定的格式。
文档体系
-
结构
-
简介（Introduction）： [必备] [文件] 提供对产品和文档本身的总体的、扼要的说明
-
快速上手（Getting Started）：[可选] [文件] 如何最快速地使用产品
-
入门篇（Basics）： [必备] [目录] 又称”使用篇“，提供初级的使用教程
- 环境准备（Prerequisite）：[必备] [文件] 软件使用需要满足的前置条件
- 安装（Installation）：[可选] [文件] 软件的安装方法
- 设置（Configuration）：[必备] [文件] 软件的设置
-
进阶篇（Advanced)：[可选] [目录] 又称”开发篇“，提供中高级的开发教程
-
API（Reference）：[可选] [目录|文件] 软件 API 的逐一介绍
-
FAQ：[可选] [文件] 常见问题解答
-
附录（Appendix）：[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容
- Glossary：[可选] [文件] 名词解释
- Recipes：[可选] [文件] 最佳实践
- Troubleshooting：[可选] [文件] 故障处理
- ChangeLog：[可选] [文件] 版本说明
- Feedback：[可选] [文件] 反馈方式
-
规则
-
Markdown文档文件后缀名使用
.md。 -
文件名建议只使用小写字母，多个单词可使用
-分隔。- 文件名不得含有空格。
- 文件名不得使用全角字符（中文不能用于文件名）。
- （为了醒目，某些说明文件的文件名，可以使用大写字母，例如
README.mdLICENSE.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 |
-
中英文混排应该采用以下规则：
- 英文和数字应使用半角字符
- 中文文字之间不加空格
- 中文文字与英文、阿拉伯数字及 @ # $ % ^ & * . ( ) 等符号之间加空格
- 中文标点之间不加空格
- 中文标点与前后字符（无论全角或半角）之间不加空格
- 如果括号内有中文，则使用中文括号
- 如果括号中的内容全部都是英文，则使用半角英文括号
- 当半角符号 / 表示「或者」之意时，与前后的字符之间均不加空格
-
中文符号应该使用如下写法
- 用直角引号（「」）代替双引号（“”）
- 省略号使用「……」，而「。。。」仅用于表示停顿
-
表达方式（语法规范）：
- 使段落成为文章的单元：一个段落只表达一个主题
- 通常在每一段落开始要点题，在段落结尾要扣题
- 使用主动语态
- 陈述句中使用肯定说法
- 删除不必要的词
- 避免连续使用松散的句子
- 使用相同的结构表达并列的意思
- 将相关的词放在一起
- 在总结中，要用同一种时态（这里指英文中的时态，中文不适用，所以可以不理会）
- 将强调的词放在句末
