在线文档规范

概要

   本文主要介绍我们在编写应用或技术文档时的一些规范

一、正文

   为保证文档内容的可扩展，可维护，应该对文档章节，格式等内容有一定的规范以及要求。本章节将从标题、正文、注释、图标等几方面展开介绍。

2.1 标题

2.1.1 标题不能跨级

   所谓跨级，一级标题下，不能直接出现三级标题

2.1.2 标题要避免孤立编号（即同级标题只有一个）

   如果当前标题下只有一个小标题，那么就没有在建立该小标题的必要。比如3.1下只有一个3.1.1，那么3.1.1就没有存在的必要啊？如果存在这种情况，那就需要考虑章节划分是否合理。

2.1.3 下级标题不重复上一级标题的名字

2.1.4 谨慎使用多级标题

   避免出现过多的标题嵌套，倘若能用列表，就用列表。我个人的原则是，如果是原则性的表述，且不需要再对齐进行解释的，那么可以使用列表，其余的一概使用标题

2.1.5 所有的标题都顶格写，不需要锁紧

2.2 文本

2.2.1 表示中文时，英文省略号（⋯）应改为中文省略号（……）

   例如：

英文：5 minutes later⋯

中文：5 分钟过去了……

2.2.2 第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可

   举例：IOC（International Olympic Committee，国际奥林匹克委员会）。这样定义后，便可以直接使用“IOC”了。

2.2.3 所有的注释都要顶格，且"注"的背景填充为黄色

   示例：

注：这是一个注

2.3 段落

2.3.1 原则

1. 段落之间使用一个空行隔开
2. 段落开头留出两个空白字符

2.3.2 引用

2.3.2.1 引用第三方内容时，应注明出处

   例如：One man’s constant is another man’s variable. — Alan Perlis

2.3.2.2 如果是全篇转载，请在全文开头显著位置注明作者和出处，并链接至原文

   例如：本文转载自 WikiQuote

2.3.2.3 使用外部图片时，必须在图片下方或文末标明来源

   例如：本文部分图片来自 Wikipedia

2.4 图注

2.4.1 图片

2.4.1.1 原则

1. 所有图片无需缩进，顶格书写
2. 图片尽量使用svg格式

2.4.2 思维导图

   由于思维导图添加元素说明相对比较麻烦，因此，我们通过颜色来进行区分，具体如下：

2.4.3 UML时序图