记录一些好的文档书写习惯。
语言风格
- 技术文档中不推荐使用只有特定人群才了解的语词，如行业黑话或网络流行语
- 正确使用的、地、得
- 不使用该、其等指代词，要说清楚
- 不使用较好、很好等修饰词，要详细说明衡量指标
文档结构样式
标题
- 一级扣一级，不跳用标题样式
- 若非必要，不使用四级及以上标题，可采用
list代替 - 标题包括不限于
- 名词词组 “…概述”
- 主题词+动词
- 动词+主题词
- 定语+主题词
- 介词+定语+主题词
- 标题中不以标点符号结尾
- 标题与标题之间应有引导性语言
段落
- 一个段落长度在 50-200 字之间，尽量不超过 250 字
- 避免只有一个句子，合理断句，避免一逗到底
- 开头不缩进，顶格开始即可
- 技术描述类主题，考虑先图表后句子
文档内容描述
空白符号
- 禁止出现全角空格
- 中文字符之间禁止出现半角空格
- 英文字符和阿拉伯数字应背半角空格包围，但在句首或右侧为半角空格时，则省略
- 不同段落、不同排版格式之间建议使用一个空行分开
Tab 和空格的使用
- 禁止混用 Tab 和空格进行缩进
列表
- 当元素间顺序不重要时，使用无序列表；当元素间顺序重要时，使用有序列表
- 使用有序列表的几个场景
- 必须按照顺序操作的步骤
- 排名分先后
- 需要在下文明确引用的规则或其他信息
- 并列列表项中采用相似的句子结构
- 每一项长度尽量接近
- 不在每一项开头采用相同的词语
- 并列列表要保持标点一致
- 前后需要加空行
- 若在列表缩进中，则在原先缩进基础上再缩进四格
- 尽量提供复制按钮，提高可用性
- 注释不应太长，一般以句号结尾
链接
- 链接格式
- 若链接到同一文档其他标题，则应为
[文档标题](#具体标题) - 若链接到相邻文档，则应为
[文档标题](../文档路径) - 若链接到外部站点，则应为
[文档标题](文档链接)
- 若链接到同一文档其他标题，则应为
- 若链接到相邻文档，且链接的文档篇幅很长，则应定位到具体引用的部分
缩略语
汉语缩略语
- 在第一次使用时说明情况
英语缩略语
- 首次使用解释完整含义
- 禁止使用无规则、不规范的缩略语
单位符号
- 为避免指代不明，建议用汉字名称代替单位符号
- 除了摄氏度、度、百分号、英尺英寸等符号外，其他情况下，数值与单位符号之间需要空一个半角空格
标点符号
- 方括号表示窗口名、菜单名，如“弹出[新建任务]窗口”
- 带尖括号表示按钮名、键名等
- 英文手册名称用中文双引号或斜体表示，不使用书名号
- 连接号
- 一字线——表示起止
- 浪纹线~表示范围
- 复合名词用短横线-
- 破折号————表示解释
- 中文语境下的标点符号必须使用全角形式
- 中英文括号的使用
- 括号里全为英文时，使用半角括号，并在括号前后各空一个半角空格
- 括号里既有中文又有英文时，使用全角括号，括号前后不空格
名称与命名
文件命名
- 文件名由多个英文单词组成时，使用-隔开
- 不建议在文件名中使用下划线
- 禁止大小写混用