标题

标题分为四级 一级标题 H1：文章的标题 二级标题 H2：文章主要部分的大标题 三级标题 H3：二级标题下面一级的小标题 四级标题 H4：三级标题下面某一方面的小标题（一般不使用）

  1. 一级标题下，不能直接出现三级标题 ```markdown

    一级标题

三级标题

  2. 2. 标题要避免孤立编号（即同级标题只有一个）
  3. ```markdown
  4. ## 二级标题 A
  6. ### 三级标题 A
  8. ## 二级标题 B
  1. 下级标题不重复上一级标题的名字 ```markdown

    概述

概述

  2. 4. 谨慎使用四级标题，尽量避免出现，保持层级的简单，防止出现过于复杂的章节；
  4. 如果三级标题下有并列性的内容，建议只使用项目列表（Item list）<br />下面的结构二要好于结构一，结构一适用的场景，主要是较长篇幅的内容
  5. ```markdown
  6. 结构一
  8. ### 三级标题
  10. #### 四级标题 A
  12. #### 四级标题 B
  14. #### 四级标题 C
  16. 结构二
  18. ### 三级标题
  20. **（1）A**
  22. **（2）B**
  24. **（3）C**

文本

字体

  1. 中文不建议使用斜体，会增加锯齿感；但是英文可以用斜体来表示文章或书籍名称

    错误：我最喜欢的一篇文章是 如何一夜暴富 。 正确：One of my favorite articles is how to get rich overnight .

  2. 一篇文章中不建议使用多种字体，尤其是在 Word 中，一般标题和正文会用不同的字体，但是正文间不建议使用多种字体，中英文字体可以用不同

字间距

有研究显示，打字的时候不喜欢在中文和英文之间加空格的人，感情路都走得很辛苦，有七成的比例会在 34 岁的时候跟自己不爱的人结婚，而其余三成的人最后只能把遗产留给自己的猫。毕竟爱情跟书写都需要适时地留白。 与大家共勉之。 —— vinta/pangu.js

全角和半角是文字的两种显示形式，“全角”指文字字身长宽比为一比一的正方形，而“半角”为宽度为全角一半的文字。现在这两个词通常用来指代计算机中显示的文字。 —— 维基百科

  1. 中英文之间需要增加空格

    错误：本文介绍如何快速启动Windows系统。 正确：本文介绍如何快速启动 Windows 系统。

  2. 中文与数字之间建议增加空格，必须保证风格统一，不能两种风格混杂

    错误：2011 年 5 月 15 日，我订购了5台笔记本电脑与10台平板电脑。 正确：2011 年 5 月 15 日，我订购了 5 台笔记本电脑与 10 台平板电脑。 对比：2011年5月15日，我订购了5台笔记本电脑与10台平板电脑。

  3. 数字与单位符号之间需要增加空格

    正确：一部容量为 16 GB 的智能手机 正确：1 h = 60 min = 3,600 s

例外：度 / 百分号与数字之间不加空格

错误：今年我国经济增长率是 6.5 %。 正确：今年我国经济增长率是 6.5%。

  1. 全角标点与其他字符之间不加空格

    错误：他的电脑是 MacBook Air 。 正确：他的电脑是 MacBook Air。

  2. 正文和链接之间建议增加空格

    正确：请 点击这里 进行订阅！ 对比：请点击这里进行订阅！

标点

  1. 不重复使用标点符号
  2. 中英文混排中，一律使用中文 / 全角标点
  3. 中英文混排中如果出现整句英文，则在这句英文中使用英文/半角标点
  4. 中文文案中使用中文引号「」和『』，其中「」为外层引号

句子

  1. 避免使用长句

    错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。 正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。

  2. 尽量使用简单句和并列句，避免使用复合句

    并列句：他昨天生病了，没有参加会议。 复合句：那个昨天生病的人没有参加会议。

  3. 同样一个意思，尽量使用肯定句表达，不使用否定句表达

    错误：请确认没有接通装置的电源。 正确：请确认装置的电源已关闭。

  4. 避免使用双重否定句

    错误：没有删除权限的用户，不能删除此文件。 正确：用户必须拥有删除权限，才能删除此文件。

写作风格

英文处理

段落

原则

如果是纯文本，段落之间使用一个空行隔开。如果是 HTML 或其他富文本格式，使用额外空白作为段落间的分隔。
段落开头不要留出空白字符。

引用

  1. 如果在正文中部分引用第三方内容，请使用恰当的引用格式并给出出处。如：

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

  2. 如果是全篇转载，请在全文开头显著位置注明出处并链接至原文，如：

    本文转载自 知乎

  3. 如果格式不允许超链接，请以文本方式直接给出原文链接。如果原文链接太长影响美观，可以使用短链接服务。如：

    本文转载自 知乎：https://www.zhihu.com/

数值

标点符号

文档体系

结构

软件手册是一部完整的书，建议采用下面的结构：

  1. 简介（Introduction）： [必备] [文件] 提供对产品和文档本身的总体的、扼要的说明
  2. 快速上手（Getting Started）：[可选] [文件] 如何最快速地使用产品
  3. 入门篇（Basics）： [必备] [目录] 又称“使用篇”，提供初级的使用教程
    1. 环境准备（Prerequisite）：[必备] [文件] 软件使用需要满足的前置条件
    2. 安装（Installation）：[可选] [文件] 软件的安装方法
    3. 设置（Configuration）：[必备] [文件] 软件的设置
  4. 进阶篇（Advanced)：[可选] [目录] 又称“开发篇”，提供中高级的开发教程
  5. API（Reference）：[可选] [目录|文件] 软件 API 的逐一介绍
  6. FAQ：[可选] [文件] 常见问题解答
  7. 附录（Appendix）：[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容
    1. Glossary：[可选] [文件] 名词解释
    2. Recipes：[可选] [文件] 最佳实践
    3. Troubleshooting：[可选] [文件] 故障处理
    4. ChangeLog：[可选] [文件] 版本说明
    5. Feedback：[可选] [文件] 反馈方式

文件名

  1. 文件名不得含有空格
  2. 文件名单词之间建议使用-分隔（all-lowercase-with-dashes）
  3. 文件名建议使用半角字符，不建议使用中文等全角字符
  4. 文件名建议只使用小写字母，不使用大写字母
  5. 某些说明文件的文件名为了醒目，可以使用大写字母，比如 README、LICENSE

参考

  1. github.com - 阮一峰 - 中文技术文档的写作规范 ⭐
  2. github.com - sparanoid - 中文文案排版指北 ⭐
  3. lengoo.de - 简体中文规范指南 | lengoo_styleguide_ZH.pdf
  4. daocloud.io - 写作规范和格式规范
  5. leancloud.cn - 文案风格指南
  6. w3.org - W3C 中文排版需求