文档规范

概要

目的

为了规范文档管理工作,提高团队协作效率,输出高质量的文档,特制定本规范。本规范文档一经确认, 所有开发人员必须按本文档规范进行执行. 本规范如有不对或者不合适的地方请及时提出, 经讨论决定后方可更改.

范围

本规范适用于项目文档、API接口文档、使用说明文档、架构文档等

文档基本准则

符合Markdown标准, 结构要有层次感,逻辑清晰简洁

文档管理

使用git仓库对markdown文档进行管理
有两种方式:

  1. 跟随代码仓库一起管理,例如在项目的根目录下有一个docs目录里面放文档
  2. 单独创建 XX_doc的仓库来管理

至于选择哪种方式,可以择优而定。若是多个项目团队共同协作文档,建议选择第二种方式。

最终文档会使用gitbook在文档服务器进行展现,由文档最高管理员统一申请域名并部署

规范

项目文档

在项目(代码仓库)的根目录下必须有一个”docs”目录,该目录下主要是用来存放相关文档

文档目录结构

文档仓库根目录必须包含以下几个文件
book.json 可选 gitbook的一些配置,比如可以指定展现的模版主题
README.md 必须 写一些相关介绍
usage.md 必须 写该项目或框架的使用说明
SUMMARY.md 必须 主要是book目录,每添加一个文档都需要在这个文件中添加目录

book.json的举例如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
"title" : "斗米客户端研发部文档",
"language" : "zh-hans",
"plugins": ["theme-comscore",
"-sharing",
"-search",
"-lunr",
"search-plus",
"splitter",
"expandable-chapters-small",
"-highlight",
"prism",
"prism-themes",
"anchor-navigation-ex"
],
"pluginsConfig": {
"prism": {
"css": [
"prism-themes/themes/prism-base16-ateliersulphurpool.light.css"
]
},
"anchor-navigation-ex": {
"showLevel": true,
"associatedWithSummary": true,
"mode": "float",
"float": {
"showLevelIcon": false,
"level1Icon": "fa fa-hand-o-right",
"level2Icon": "fa fa-hand-o-right",
"level3Icon": "fa fa-hand-o-right"
},
"pageTop": {
"showLevelIcon": false,
"level1Icon": "fa fa-hand-o-right",
"level2Icon": "fa fa-hand-o-right",
"level3Icon": "fa fa-hand-o-right"
}
},
"theme-default": {
"showLevel": false
}
}
}

针对SUMMARY.md举例如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Summary
* [介绍](README.md)
* [使用说明](usage.md)
* [组件拆分最佳实践](best.md)
* [grain配置](config.md)
* [javascript API](api.md)
* [缓存类API](api/cache.md)
* [位置类API](api/location.md)
* [信息类API](api/clientInfo.md)
* [安全类API](api/safety.md)
* [定制界面类API](api/clientUi.md)
* [原生功能类API](api/widget.md)
* [自定义API](api/customize.md)

Markdown书写规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1. 段落与段落之间空一行表示。
分节的时候可以多空一行。单个回车视为空格,连续回车才是换行。(行尾加两个空格,可以段内强制换行,一般用户可以忽略。)
2. 其实在网络上你可以完全抛弃开头空两格的习惯,代之以段落之间空一行的习惯。如果只要要开头空两格,那么可以输入 来表示一个空格, 为两个。或者使用输入法切换到全角,双击空格键。
3. 标题:# 一级标题
“#”之后最好加一个空格,这在md单向标记中都最好使用
也可以把”=“写在标题(H1)下面的一行,表示上面一行的文字为标题,”-“写在下面便是小标题或是节标题(H2)。
4. 加粗,斜体:**加粗**,*斜体*,***粗斜体***
5. 引用:>
6. 行内源代码:‘代码'。行的开头空四个空格,缩进内容视为代码块。代码块也可以用’‘’代码‘’‘来完成。当然简单的用'代码'也可以显示。
7. 删除线:~~删除~~
8. 层次(也就是类似目录列表的东西):“*” 后面要加空格,这是必须的,除了 *,还可以使用 + 或者 -。
1. 第一节
2. 第二节
* 第一小节(推荐每层次缩进四个空格)
* 小小节 1
* 小小节 2
* 第二小节
9. 链接,图片:[想要显示的文字](链接,"Title"),![(图片说明)](图片链接)。段落内使用的时候左右各空一格,除非是使用列表的时候。
此外,还可以以索引方式把url都列在文章的最后,例如这样:
[文字][1]
[1]: 链接(不要忘记冒号后面的空格,title的写法与上类似)
10. 分割线:---,上下各空一行,也可以用***,其实只要三个以上,随便你怎么写。
11. 其他:
[链接标题][null-link],可以生成一个伪链接样式,也就是存在链接的样式,但没有实质的链接。更高级的链接写法:[文字][hover]
[hover]:链接"悬停文字"
图片链接:
[![][jane-eyre-pic][jane-eyre-douban]
[jane-eyre-pic]: http://img3.douban.com/mpic/s1108264.jpg
[jane-eyre-douban]: http://book.douban.com/subject/1141406/
若要在图片下线是说明:{ImagCap}说明{/ImgCap}
12. 跟其他的编程语言一样,利用转意字符”/“就可以输出”[“这类符号