OverWatch团队文档格式规范
V1.0
最终修改于2016/10/19
概述
软件工程中，一份优雅的文档不仅能降低团队成员之间的沟通难度，而且能给之后的开发者提供一个非常有效的引导。本团队为了规范整个项目中文档的格式，便于统一管理与清晰的阅读，特制订以下格式规范。
为了方便博客端和Github端的文档统一编写，统一风格，因此选用Markdown语法作为文档编写的格式。但是由于Markdown为纯文本格式，对图片、颜色、表格等元素的支持非常困难，因此在编写图片表格较多的博客时，允许使用Microsoft Office Word中的博客功能进行编辑，本团队cnblogs博客中已经对于html和Markdown格式进行了统一的CSS样式处理，可以得到统一的样式风格。但是由于目前还不能将Word样式的表格转换为Markdown格式保存在Github中，因此在编写表格和图片不多的文档时还是应该尽量使用Markdown，方便同时上传至博客和Github中。
格式规范
不论是在Markdown还是在Word中，为了应用博客和Github中预设好的CSS样式，需要将文档的的格式规范化。本文将格式大致分为三个部分标题、文本样式和文本组织
标题
标题是文档的逻辑组织结构最重要的标识。建议将文本分成清晰的树状逻辑结构，并用标题加以标识和区分。html中一共提供了6级标题，但是我们只使用其中的三个：标题1、标题2、标题3。分别代表了三个从高到低的逻辑层次，样式如下
标题1示例
标题2示例
标题3示例
如果标题之间逻辑层次较强，或者标题较多，可以对标题进行编号，统一使用标题1序号.标题2序号.标题3序号的形式，序号均为阿拉伯数字，序号和标题之间有一个空格。样式示例如下
1 这是标题1
1.1 这是标题2
1.1.1 这是标题3
文本样式
加粗
对于需要强调的文本部分，应给予加粗，示例如下
这是无关紧要的这是重要的这也是无关紧要的
行内代码
对于某些专业名词，或者其他需要用这个样式强调的部分应标记为行内代码，示例如下
我正在使用
Markdown
文本组织
列表
对于某些并列关系强的文本，且每段文本长度并不是很长（一行左右），应采用列表方式呈现，一般来说不建议使用带有序号的列表，且最好不要列表下嵌套列表。示例如下
- 我今天要吃饭
- 明天也要吃饭
- 后天就撑死了
引用
对于某些其他文章的摘抄或者转述，或者因为格式需要需要开辟一小块类似文本框的区域时，应采用引用（其实每一个之前的示例都是写在引用里面的）。示例如下
床前明月光
疑是地上霜
举头望明月
低头思故乡
代码
所有语言的代码，应写在代码框中，而不是直接截图，方便他人直接拷贝和阅读（因为有不同语法成分高亮的功能），示例如下
int main()
{
printf("this is a test.");
}
Markdown语法
在介绍Markdown的语法之前，首先推荐一款Markdown编辑器。虽然有很多在线的编辑器，但是经我试用以后体验都不是很好，而且需要网络的支持，有着很多的局限性。在试用了很多软件之后，我发现Typora 这款软件比较适合在PC端进行Markdown的编写。这款软件能实时渲染最终效果，而不是像其他软件那样一边是代码一边是预览，而是所见即所得，直接在一个窗口内编辑且直接看到最终的效果。
这是下载地址Typora
下面继续将从 标题、文本样式、文本组织三个方面来介绍Markdown的语法
标题
在Markdown中，标题的输入方式是在标题前加入#（没有空格），根据#数量的不同，分别表示1级~6级标题
比如#+这是一个一级标题和##+这是一个二级标题，显示效果是这样的
这是一个一级标题
这是一个二级标题
在我们的文档规范中，标题只使用1~3级。
文本样式
加粗
在Markdown中加粗一段文本可以用在文本前后各加入两个*来实现
比如**+这是一段加粗文本+**，显示效果是这样的
这是一段加粗文本
而在Typora 中，要输入加粗文本有一个快捷键ctrl+B，程序会自动打出前后各两个*并将光标移到其中，可以直接输入加粗文本的内容。
行内代码
在Markdown中将一段文本设置成行内代码可以用在文本前后各加入一个`来实现
由于`不能嵌套，这里不能演示示例
在Typora 中，行内代码同样有一个快捷键ctrl+`，程序会自动补全并将光标移到其中，可以直接输入行内代码的内容。
文本组织
列表
在Markdown中将一段文本设置为无序列表可以用在其之前加入*、+或者-来实现，注意中间需要有一个空格，如
*+ Space+第一项内容
*+ Space+第二项内容
显示效果如下
- 第一项内容
- 第二项内容
而在Typora 中，如果输入了第一个列表项，按下Enter后，将会自动生成下一个列表项，如果已经输入结束，可以连续打两个Enter来退出列表项的编辑。
顺便一说，加入1.+Space可以生成有序列表项，但是格式规范并不推荐这样做。
引用
在Markdown中将一段文本设置为引用可以用在其之前加入>来实现
例如>+这是一段引用
这是一段引用
Typora中插入引用的快捷键是Ctrl+Shift+Q
代码
在Markdown中将一段文本设置为代码可以利用Typora中的快捷键Alt+Ctrl+F来实现
在代码块中可以选择程序语言，以便提供不同的高亮展示，例如
int main()
{
printf("this is a test.");
}
其他
超链接
可以利用Typora中的快捷键Ctrl+K来实现
按下快捷键后，程序会自动补全[]和()，前者是超链接显示的文本，后者是超链接的链接地址
表格
在Typora中按下快捷键Ctrl+T可以方便的插入表格，可以选择行列数，替代了原生Markdown语法反人类的表格编辑方式。
更多
这里只介绍了一部分Markdown的语法，关于全面的语法介绍，可以参考这个网址Markdown语法说明（中文版）
Word博客写作规范
由于Markdown是纯文本模式，对于某些表格和图片较多的博客，如Scrum Meeting总结这样有大量图片和表格的博客内容支持并不是很好（或者说是虽然支持但是不是很美观和易用）。考虑到这些富图片和表格的博客多为记录，并不需要同步发布在Github中，所以这些博客仍然使用Word博客功能进行编写。
关于Scrum Meeting博客，现在已经有了一套模板Docx文件，今后可以直接在这上边修改发布。如果需要有其他的博客需要利用Word进行编写，在下面介绍一些编写规范。
整体格式规范
- 所有文本都不应设置自定义的字体，应保持默认状态。这样做的目的是为了不覆盖博客中的CSS模板设置的字体
- 所有文本都不应该设置自定义字号，保持默认状态，原因同上
- 所有大小标题使用
Word自带的标题1、标题2等进行设置 - 如需要引用，可以直接使用
Word中自带的引用，可以在博客中被自定义样式识别并适配 - 可以直接加粗文本
- 可以直接使用
Word自带的列表
一些特例
- 如需要行内代码，请将文本标为
斜体 - 如需要使用代码块功能，请先发表后在博客园的编辑器中进行插入
- 如需要使用超链接功能，请先发表后在博客园的编辑器中进行插入
