中文技术文档风格指南 ¶

语言风格 ¶

对话式 ¶

• 「你可以……」
• 平易近人、直截了当
• 避免过于口语化，冗长啰嗦、缺乏逻辑

客观礼貌 ¶

• 对于指导性文档，保持冷静、客观、简洁的语气
• 避免使用拟人的写作手法
• 不要穿插太多玩笑
• 不要使用反问句
• 不要轻易使用感叹句
• 不要轻易使用“请”、“抱歉”，除非真的对读者造成了困扰
• 避免过分亲切的称呼

简洁清晰 ¶

• 禁止啰嗦冗长
• 禁止逻辑混乱
• 同一文档中勿重复表达同一事物
• 尽量用主动时态，尤其要阐述清楚主语和宾语

通俗易懂 ¶

• 不推荐使用行话黑话、俚语、脏话等
• 不推荐使用网络流行语

用户导向 ¶

• 充分考虑文档受众的技术水平分布以及实际操作中可能出现的问题
• 对于操作型技术文档，除语言审校外，建议继续进行“文档可用性测试”
• 对于操作型技术文档，不仅要准确描述操作步骤，还应设身处地考虑用户可能面临的问题，提供进一步的详细信息

用词恰当 ¶

• 用词正确及用词统一
• 禁用词参考《新华社新闻报道中的禁用词（第一批）》
• 常用词
  • 必须用对“的”、“地”、“得”，不能乱用
  • 必须明确“其”、“该”、“此”、“这”等代词指代的内容，保证不造成歧义
  • 不建议使用表示程度、强调语气的词
  • 不建议使用冷僻、生造或者文言文的词语
  • 禁止使用过多的形容词修饰名词
• 统一用词
  • 必须保证全文人称代词一致，人称不能反复改变
  • 建议尽量使用主动语态，不使用被动语态

文档结构样式 ¶

标题 ¶

• 从一级开始递增使用，禁止跳级使用
• 最多不超过四级
• 一级标题最多出现一次且为文章标题
• 三级标题下有并列性的内容建议使用列表替代
• 标题文本
  • 概括反映本章节的中心内容
  • 简洁扼要、涵义明确
  • 同级别的标题尽量使用相同的结构
  • 标题描述操作任务时建议使用“动词 + 主题词”结构，不建议使用名词词组
• 注意事项
  • 下级标题禁止重复上一级标题的内容
  • 不建议标题以标点符号结尾
  • 不建议在标题中解释缩略语
  • 标题与标题之间应该有引导介绍性的句子。
  • 标题要避免孤立编号（即同级标题只有一个），正文不要有孤立的三级标题和四级标题
  • 项目列表是最小编号单位，项目列表下禁止嵌套任何级别的标题

段落 ¶

• 一个段落只能有一个主题，或一个中心句子
• 段落的中心句子建议放在段首，对全段内容进行概述
• 一个段落的长度建议在 50～200 字之间，尽量不要超过 250 字
• 段落之间建议设置合适的间距，提高可读性
• 技术文档的段落开头不建议缩进
• 对于技术描述类主题，应考虑先图表，后句子的原则

句子 ¶

• 避免使用长句，一个句子建议不超过 100 字
• 使用简单句和并列句，避免使用复合句
• 避免”一逗到底”的情况，合理断句

文档内容元素 ¶

空白符号 ¶

空格 ¶

• 禁止使用全角空格，一律使用半角空格
• 中文字符（包括汉字和中文标点符号）和中文字符之间禁止空半角空格
• 英文字符和阿拉伯数字一般使用半角格式，所以应使用半角空格包围，以下情况例外
  • 位于句首时，左边空格省略
  • 其右侧为半角标点或全角标点时，右边空格省略
• 除表示缩进、列表级别、代码块中固有空格、markdown 表格中的空格外，禁止连续出现两个及以上的半角空格
• 不建议使用 Tab（制表符）替换空格

空行 ¶

• 不同段落间建议使用一个空行隔开
• 不同排版格式之间建议使用一个空行隔开，如标题与紧跟着的正文之间，正文与代码块之间、正文与表格之间等
• 禁止连续出现两个及以上的空行

列表 ¶

• 当列表项之间的顺序不重要时，使用无序列表；当各项之间的顺序很重要时，使用有序列表
• 并列列表项中建议使用相似的句子结构
• 每一项的长度要尽量接近
• 避免在每一项开头重复相同的词语
• 使用清晰的、描述性的句子或短语来引出列表
• 并列列表项中保持标点符号一致
  • 若列表项是句子，那么每一项建议以句号结尾
  • 若列表项是词组，则不建议以任何标点结尾
  • 若列表项既有词组又有句子，则建议统一以句号结尾
• 避免嵌套使用列表，这样通常会显得冗长复杂
  • 如果一定要表现多层级的列表，建议最多不超过 3 级，且每一级都要用不同样式的小圆点
• 一个操作任务的步骤描述通常要使用有序列表
  • 为方便用户记忆，建议严格限制列表项在 7 个以下，最多不要超过 9 个步骤

表格 ¶

• 所有内容都建议保持左对齐
• 所有表格都需要有表头描述，即表格第一行中描述各列内容的短语
• 保证表格同一行的单元格不跨页
• 每个表格下都要空一行，且这一空行的样式为正文
• 同一技术文档或产品手册中相同类型表格的表头描述需要保持一致
• 表格中的内容应该尽量简练，文字表述风格保持一致
• 不出现空白的单元格，建议无内容单元格填写“无”或特定含义符号（如“/”）
• 如果多个单元格中的内容相同，建议将内容复制或者采用多个单元格合并的方式，不要使用“同上”

图形图片 ¶

• 中文文档里图形图片上的文字建议都用中文，如果原图文字是其他语言，应该先做好图片本地化工作
• 同一文档内图形图片上的文字应该统一字体
• 图形图片中避免出现大段文字，描述性语言建议放到图外
• 图形图片中包含缩略语时，需要在图说明中对缩略语进行解释
• 图说明和图尽量保证在同一页中显示
• 图片的命名建议使用描述性的文字
• 插入图片时建议添加替代文本，从而改进文档的无障碍访问

代码块 ¶

• 代码块前后必须加上一行空行
• 代码块要注意缩进
• 如果前端支持，建议高亮代码块，方便阅读
• 如果前端支持，建议为代码块加上可供用户直接复制代码的按钮，提高文档易用性
• 一行注释不能太长，太长时应适当进行断句并切分到下一行
• 必须根据代码块中定义的语法选择相应的注释符，不能自创注释符

链接 ¶

• 链接描述必须能概括所链文档或页面的大致内容，这有利于搜索引擎优化
  • 比如不能出现：点击这里
• 同类型的链接描述应尽量统一风格
• 如链至其他相邻文档，且链接的文档篇幅较长，建议链接至锚点
• 不建议混用相对路径和绝对路径
• 建议减少将用户链至外部站点的次数，以免外部站点的页面失效而影响用户体验
• 如果必须将用户链至外部站点，建议在该外链后加上明显的标示，提醒用户该链接将前往外部站点

引用 ¶

• 当某内容在其他地方已经详细描述过、不适合在正文中再次介绍时，可以使用引用
• 对于必须引用但内容很少（少于 100 字）的情况，建议直接在该处重新描述一遍
• 必须保证引用的位置准确。
• 引用第三方内容
  • 引用他人的语句时，应注明出处
  • 全篇转载时，应在全文开头显著位置注明作者和出处，并链接至原文
  • 使用外部图片时，必须在图片下方或文末标明来源

缩略语 ¶

• 保证汉语缩略语通俗易懂、不造成歧义，原则上不限制使用次数
• 如果某词在文档中必须大量使用，但其缩略语不常见，建议在该词第一次出现时说明情况，提示读者下文中将以缩略语的形式称呼该词
• 禁止使用不规范的缩略语
• 不建议在标题中解释英文缩略语，以免造成标题冗长

数字 ¶

• 选用阿拉伯数字
  • 用于计量（即用于加、减、乘、除等数学运算）的数字
  • 当数值伴随有计量单位时
  • 用于编号的数字
  • 希望突出简洁醒目的表达效果时
• 选用汉字数字
  • 数字连用表示的概数、含“几”的概数等（如三四个月）
  • 干支纪年、农历月日、历史朝代纪年及其他传统上采用汉字形式的非公历纪年
  • 汉语中长期使用且已稳定下来的包含汉字数字形式的词语
  • 希望突出庄重典雅的表达效果时
• 在同一场景出现的数字，应遵循“同类别同形式”原则来选择数字的形式
• 应避免相邻的两个阿拉伯数字造成歧义的情况
• 有法律效力的文件、公告文件或财务文件中可同时采用汉字数字和阿拉伯数字

阿拉伯数字格式 ¶

• 数字与英文字母一样，一律使用半角形式
• 在不作任何后期排版处理的前提下，建议半角数字两旁各空一个空格
• 一个用阿拉伯数字书写的数值必须在同一行中，不能断开移行
• 数值巨大的精确数字，建议使用“亿、万”作单位
• 数值为千位以上，建议添加半角逗号“,”作为分节符
• 在表示数值的范围时，可采用浪纹式连接号“～”或一字线连接号“—”
• 前后两个数值的附加符号或计量单位相同时，在不造成歧义的情况下，前一个数值的附加符号或计量单位可省略

汉字数字格式 ¶

• 两个数字连用表示概数时，建议两数之间不用顿号隔开
• 年份简写后的数字可以理解为概数时，一般不简写（例如“一九七八年”不写为“七八年”）
• “零”与“〇”
  • 一个数字用于计量时，建议用“零”
  • 用于编号时，建议用“〇”（如年份）
• “二”与“两”
  • “二”“两”在度量衡单位和百千万前面可以通用
  • 序数、分数、小数用“二”，不用“两”
  • 常用量词（如个、本、件、回、种、天）前面，用“两”不用“二”
  • 用“二”和“两”的地方如果强调计量和统计意义时可以用“2”

单位符号 ¶

• 建议用汉字名称代替单位符号
• 大多数情况下，数值与单位符号之间需要空一个半角空格

标点符号 ¶

中文标点符号按照正常汉语规范使用，不过多介绍，以下是需要注意的地方：

• 中文语境下的标点符号一律使用全角形式，不得使用半角形式
• 中文全角标点符号两旁禁止空半角空格
• 注意避头尾规则

中英文混排 ¶

• 中文句子内夹用英文单词或词组时
  • 夹用的英文单词或词组可不用中文引号包裹
  • 如果夹用的英文单词或词组本身带有英文标点，保留其英文标点
  • 中文句子句末均以中文标点符号结尾
• 中文句子内夹用英文句子时
  • 用中文引号包裹引用该英文句子
  • 如果夹用的英文句子本身带有英文标点，保留其英文标点
  • 中文句子句末均以中文标点符号结尾
• 英文标题或引文中结尾标点
  • 结尾问号必须保留
  • 结尾叹号必须保留
• 中英文括号使用
  • 括号里全为英文时建议使用半角括号，并在括号前后各空一个半角空格，括号和括号内的英文之间不需要空格
  • 括号里既有中文又有英文（即只要括号内包含任何中文）时建议使用全角括号，括号前后不空格
• 中文句子中夹用英文书籍或报刊名时，不能使用中文书名号《》，而应使用斜体字表示，如果无法使用斜体字，建议使用中文引号包裹引用
• 英文文章的标题用中文引号包裹引用

拼写 ¶

• 简体中文和繁体中文不能混用
• 禁止出现中英文错别字
• 英文大小写形式
  • 英文大小写形式不能写错
  • 当中文句子中夹有英文单词或词组时，无论该英文单词或词组位于中文句子的开头、中间还是末尾，普通单词、词组必须小写，专有名词等在英文中必须大写的单词或词组，保留其大写形式
  • 当中文句子中夹有完整的英文句子时，无论该英文句子位于中文句子的开头、中间还是末尾，其首字母均保留大写形式
• 名称使用
  • 对于中文读者熟知其中文官方译名的公司、品牌或产品名称，只需用中文官方译名指称
  • 对于中文读者不熟悉、但有中文官方译名的公司、品牌或产品名称，建议用“中文官方译名 ( 英文官方名称 )”形式
  • 对于无中文官方译名的公司、品牌或产品名称，建议直接用英文指称，且必须使用正确的大小写形式