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自带的列表

一些特例

• 如需要行内代码，请将文本标为斜体
• 如需要使用代码块功能，请先发表后在博客园的编辑器中进行插入
• 如需要使用超链接功能，请先发表后在博客园的编辑器中进行插入