V1.0

最终修改于2016/10/19

概述

软件工程中,一份优雅的文档不仅能降低团队成员之间的沟通难度,而且能给之后的开发者提供一个非常有效的引导。本团队为了规范整个项目中文档的格式,便于统一管理与清晰的阅读,特制订以下格式规范。

为了方便博客端和Github端的文档统一编写,统一风格,因此选用Markdown语法作为文档编写的格式。但是由于Markdown为纯文本格式,对图片、颜色、表格等元素的支持非常困难,因此在编写图片表格较多的博客时,允许使用Microsoft Office Word中的博客功能进行编辑,本团队cnblogs博客中已经对于htmlMarkdown格式进行了统一的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自带的列表

一些特例

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

OverWatch团队文档格式规范的更多相关文章

  1. Atitit usrQBK1600 技术文档的规范标准化解决方案

    Atitit usrQBK1600 技术文档的规范标准化解决方案 1.1. Keyword关键词..展关键词,横向拓展比较,纵向抽象细化拓展知识点1 1.2. 标题必须有高大上词汇,参考文章排行榜,1 ...

  2. 【好文翻译】一步一步教你使用Spire.Doc转换Word文档格式

    背景: 年11月,微软宣布作为ECMA国际主要合作伙伴,将其开发的基于XML的文件格式标准化,称之为"Office Open XML" .Open XML的引进使office文档结 ...

  3. 【itext】7步制作兼容各种文档格式的Itext5页眉页脚 实现page x pf y

    itext5页眉页脚工具类,实现page x of y 完美兼容各种格式大小文档A4/B5/B3,兼容各种文档格式自动计算页脚XY轴坐标 鉴于没人做的这么细致,自己就写了一个itext5页眉页脚工具类 ...

  4. C#word(2007)操作类--新建文档、添加页眉页脚、设置格式、添加文本和超链接、添加图片、表格处理、文档格式转化

    转:http://www.cnblogs.com/lantionzy/archive/2009/10/23/1588511.html 1.新建Word文档 #region 新建Word文档/// &l ...

  5. Java导出freemarker实现下载word文档格式功能

    首先呢,先说一下制作freemarker模板步骤, 1. 在WPS上写出所要的下载的word格式当做模板 2. 把模板内不固定的内容(例:从数据库读取的信息)写成123或者好代替的文字标注 3. 把固 ...

  6. wordxml文档格式说明

    近期需要对word xml文档进行各种操作,需要熟悉 wordxml 文档格式,搜索了一番后发现 open xml sdk 官网的文档最好.就按照官网说明来记录一番 1 word xml 文档基本格式 ...

  7. windwos文档格式转换成unix格式

    在工作学习中我们避免不了需要将一些脚本和命令记录在笔记里面,我使用的是有道云笔记,每当我将上次记录在有道云的脚本复制出来进行使用的时候,总会报一些奇怪的错误,要么是包含换行符,要么就是格式不对,但是我 ...

  8. 导出WPS office文档格式的说明

     针对microsoft office的文档格式,WPS office分别提供wps对应doc,et对应xls两种格式,word和excel是办公系统使用的普及度最广的文件格式,而国内的政府行政单 ...

  9. Java利用jacob实现文档格式转换

    实现文档格式之间的转换,我使用的是jacob-1.7版本,需要jacob.jar来调用activex控件,本机需安装WPS/office,还需要jacob.jar以及jacob.dll 其中:    ...

随机推荐

  1. ubuntu 下安装 texlive 并设置 ctex 中文套装

    1 安装 texlive2013 1.1 下载 texlive2013 下载地址:http://ftp.ctex.org/mirrors/CTAN/systems/texlive/Images/tex ...

  2. nginx 日志相关配置总结

    设置位于nginx.conf:         log_format  main  '$server_name $remote_addr - $remote_user [$time_local] &q ...

  3. Linux服务器磁盘扩展和oracle表空间文件迁移操作记录

    1.环境介绍 服务器硬件:Dell R710 服务器OS:红帽子Linux   RHEL4.8 数据库:Oracle 10g 2.出现的问题 因为数据表每天有上百万的数据写入表,加上建立索引,导致表空 ...

  4. 《javascript》高级程序设计——类型转换错误

    容易发生类型转换错误的另一个地方,就是流控制语句.像if之类的语句在确定下一步操作之前,会自动把任何值转换成布尔值.尤其是if语句,如果使用不当,最容易出错.来看下面的例子. function con ...

  5. MySQL双主(主主)架构方案

    在企业中,数据库高可用一直是企业的重中之重,中小企业很多都是使用mysql主从方案,一主多从,读写分离等,但是单主存在单点故障,从库切换成主库需要作改动.因此,如果是双主或者多主,就会增加mysql入 ...

  6. js面向对象与原型

    创建对象 var box = new Object();//创建对象 box.name = 'Lee'; //添加属性 box.age = 100; box.run = function(){ ret ...

  7. 高阶Laplace曲面形变算法(Polyharmonic Deformation)

    数学上曲面的连续光滑形变可以通过最小化能量函数来建模得到,其中能量函数用来调节曲面的拉伸或弯曲程度,那么能量函数最小化同时满足所有边界条件的最优解就是待求曲面. 能量函数通常是二次函数形式: 其中S* ...

  8. 第27章 java I/O输入输出流

    java I/O输入输出流 1.编码问题 import java.io.UnsupportedEncodingException; /** * java涉及的编码 */ public class En ...

  9. JSP前三章测试改错

    分析:文件.数据库都是持久化保存数据的,所以是正确的,而servletcontext是上下文对象当然也可以.所以正确答案为A 分析: A:判断学员是否手动安装过Tomcat(练习熟练度) B:使学员了 ...

  10. Mui沉浸模式以及状态栏颜色改变

    沉浸模式只需要设置下就可以  ios:  打开应用的manifest.json文件,切换到代码视图,在plus -> distribute -> apple 下添加UIReserveSta ...