文档格式指南-标点符号-专有名词

概述

参考资料

1. 华为 - 产品手册中文写作规范
2. 中文文案排版手指北

规范

命名

• 前缀 + 连接符 + 实际名称
  • 前缀：表明类别、日期、版本等信息
• 连接符
  • 文件夹：首字母大写：Documents
  • 中文文件名：中划线：文档规范-标点符号.md
  • 西文文件名：下划线：test_name.md
    • 符合 Python 命名规范
    • 在鼠标双击时能被视为一个整体。
• 实际名称：
  • 达意原则：见名知意，准确表达事物的含义，使名称清晰、明确、直观。
  • 长度限制：标识符的长度不能超过 32 个字符，过长需采用易理解的缩写。

内容

• 全面性：考虑周到，覆盖全面。
• 正确性：正确是前提。
  • 错别字：确保无错别字
  • 即使是流行语中故意的谐音错别字也不要使用，比如「墙裂」、「童鞋」等。
  • 合理使用容弄混的词：如「你」和「您」：在不是很正式或没有明确的个体指代对象的时候用「你」，如文档、博客、群发的邮件等；在指代特定个体时请用「您」，如活动邀请函等。
• 文风精练：对意思表达没有明显作的字、词、句去掉，保证表达效果的前提下将文案长度减到最短。

目录

目录：反映所有章节及附录的内容。

• 文档需有目录，采用层级式格式撰写，模块内容应有模块目录。
• 技术手册、安装手册的附录中应包含图、表的目录，并进行表说明（Table Description）与图说明（Figure Description）的描述。

标题

标题：概括反映章节的主要内容，要求简洁扼要，语义确切。

• 采用四级标题制，层层递进，不能跨级，更下层采用列表
• 避免同级标题只有一个
• 下级标题不能重复上级标题名字，标题中不带标点符号
• 标题应概括反映章节的中心内容，
• 如一级标题和二级标题之间应有引言
• 二级标题和三级标题之间应有正文内容
• 项目列表（Item list）是小编号单位。项目列表下面不可以嵌套子标 题。 内容是表示操作步骤和并列关系的分 句

常用标题写法

• 短语，简单句或单句描述；
• 名词词组，如“概述”、“规格参数”。
• 主题词＋动词，如“母板插框槽位说明”。
• 动词＋主题词，如“配置用户数据”。
• 定语＋主题词，如“交换网板的安装”，“交换网板的结构”。
• 介词＋定语＋主题词，如“对空间规划的要求”。

风格注意事项

• 同一级标题建议用一种结构表达；
• 下级标题不重复上一级标题的内容；
• 高一级标题下不应只有一个次级标题，同时避免孤立的章节和标题存在；
• 四级标题以上的标题之间应该有正文内容；

文本

• 全角中文字符与半角英文字符和半角阿拉伯数字之间，应有一个半角空格。
  • （半角）英文的左右保持一个空白，避免中英文字黏在一起；
• 半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。
• 使用全角标点符号；
• 严格遵循 Markdown 语法；
• 「加亮」和「加粗」和「链接」都需要在左右保持一个空格。

段落

段落：主题信息块的基本构成单元之一，由多个句子组成。

• 一段一主题，中心句放句首，进行概述，后面的陈述句作为说明、展开、论述。
• 内容尽量用陈述与肯定语气，避免感叹语气。
• 一段不超过 7 行，最好小于等于 4 行，连续的段落不能超过 1 页，一个段落块建议不要超过 3 个段落。
• 段落之间使用一个空行隔开。
• 对于技术描述类主题，图表优于句子段落。

句子

句子：以句号结尾，表示句子已完成。

• 避免长句，一个句子不超过 100 字（正文 3 行）。
• 简单句 + 并列句，避免复合句。
• 避免歧义，常见结构如：
  • 名词 1 ＋名词 2 ＋名词 3
  • 词性的变化，如“配置管理界面”
  • 动词＋形容词＋的＋名词，如“如“检测故障的电路””
  • 名词 1 ＋ 的＋（名词 2 ＋和＋名词 3）。如“系统的时钟和主控单元”。
  • 等

引用

第三方引用

• 正文中引用第三方内容，采用合适的格式给出出处。如：

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

• 全篇转载，需在全文开头显著位置注明出处并链接至原文，如：

  本文转载自 WikiQuote

内部内容引用

系统内资源的引用，需保证引用的位置准确，

对于内容很少（小于 100 字）但必须引用的情况建议直接在该处重新描述一遍；对于内容很多不利于重新描述的，可以采用引用。

缩略语

缩略语：Abbreviations：包含缩写和只取首字母的缩写词。

• 正文中第一次出现的缩略语，必须进行解释。

• 在技术手册、操作手册、维护手册、设备手册、用户手册、产品概述、安装手册、命令手册、验收手册、出厂检验报告、成套资料使用指南、安全手册后，需提供缩略语表作为附录，

• 中文的正文缩略语解释格式：VPN（Virtual Private Network），括号中的解 释不需要提供中文说明。

  缩略语表保持以下样式。

术语

Term：术语：对于在技术、操作、维护手册中出现的重要技术术语（Term）要给予解释。可以 在手册正文说明，也可以在术语表（Glossary）中说明。

• 技术术语的解释原则为便于用户快速理解这一术语的相关意义。
• 中文术语按拼音声母排序。
• 术语表放在缩略语表之前。

项目列表

项目列表：Item List：用于表示步骤或并列关系

• 为方便记忆，操作任务应限制在 7 个或更少的单步操作 下，最多不要超过 9 个步骤。
• 简单的术语和词汇； z 短语、简单句或单句描述。

表格

表格：Table：

• 样式需直观、美观
• 表格下方空一行，
• 相同类型的表格的表头内容须一致，不要采用同义词，须统一。
• 内容简练，单元格中内容不超过 6 行，

图像

图像

• 禁止直接引用背景透明的位图图标
• 禁止使用占用磁盘空间太大的图形格式。
• 界面图禁止使用 JPG 格式，建议用 GIF 或 PNG 格式。
• 图形中中文字体采用“宋体”，字母与数字采用“Arial”字体。
• 图形中避免出现大段文字，描述性语言建议放到图外，用编号替代。
• 同一产品手册必须采用相同的标准。
• 图形中包含缩略语时，需要在图说明中对缩略语进行解释。
• 图形的说明和图尽量统一在一页上。如果分布在相邻的两页上，应保 证该两页是相对的，而不是相背的（即先偶数页，后奇数页）。
• 需注意图像上的文字无法自适应屏幕大小与分辨率。

数值

• 数字一律使用半角形式，不得使用全角形式。
• 对于 4 ～ 6 位的数值，千分号是选用的，比如 1000 和 1,000 都可以接受。对于 7 位及以上的数值，千分号是必须的。
  • 多位小数要从小数点后从左向右添加千分号，比如 4.234,345。数值为千位以上，应添加千分号（半角逗号）。RMB1,258,000
• 表示数值范围时，用 ～ 连接。
• 数字带有国际单位和表示量的数词时，两个数字都要加上数词和单位。
  • 正确的使用方法：132kg ～ 234kg，67%～ 89%，50kV ～ 100kV，70kPa ～ 106kPa。
  • 错误的使用方法：132 ～ 234kg，67 ～ 89%，50 ～ 100kV，70 ～ 106kPa。
• 对于需要强调的特别书面信息，格式不定，但要全文保持统一。如第 1 章。
• 文字型数值：
  • 极其正式的文件中，如公告、社交请帖
  • 定型的词组、术语、带有修饰色彩的词语中使用文字格式。如三三制、五局三胜制、二十挂零、第三季度。
  • 时间使用文字型数字的情况：
    • 农历年份。如，正月初五，丙寅年十月十五日；
    • 含有时间简称来表示时间、节日的词组。如“九一三”事件，五四运动。
• 阿拉伯数字：

  • 统计表中的数值，如正负整数，小数，百分比，分数，比例，必须使用阿拉伯数字。

  • 物理量量值必须用阿拉伯数字，并正确使用法定计量单位。

    • 如 米 (m)、弧度 (rad)

  • 代号、代码和序号 文件编号，证件号码，其他序号，用阿拉伯数字。如 HP-3000 型，维生素 B12

  • 时间使用阿拉伯数字的情况：

  • 公历世纪、年代、年、月、日使用阿拉伯数字。如，20 世纪 80 年代， 2003 年 7 月 30 日。（一般，“1990 年”在技术文档中不能简写成“90 年”）；

  • 在表格、索引、年表中，年月日可以表示为“2003-07-30”。月和日 为个位数时，要加“0”补充； z 时、分、秒。

  • 正式情况，采用如下格式：14 时 12 分 36 秒。其他情况， 按照 GB-T 7408-94-5.3.1.1 要求，使用扩展格式：14:12:16。“:”使 用 Arial。

  • 电话号码：

  • z 没有区号时：12345678 z 国内区号时：0755-12345678 z 国家区号时：+86-755-12345678 z 800 电话：8001234567 z 电话号码范围：12345000 ～ 12348000；12345678/79/80 固定电话号码举例时，局号要用“1”开头（即举例的号码用 1 开头）。 区号可以按照实际情况举例。

  • 手机号码的举例中，格式如下：

    z 联通用户时，13300001234 z 移动用户时，13900001234

日期时间

• 日期应按照中国的习惯表示法表示为
  XXXX 年 XX 月 XX 日
  • 例如：2017 年 5 月 15 日
  • （视上下文）例如：公历 2018 年 02 月 04 日至 03 月 05 日
• 时刻的表示法可保留原文格式或改写为中文格式。
  • 例如：“8:00 a.m.”或“上午 8:00”。
• 下表为一般及缩写的英文星期格式所对应的中文译法：

英文格式	应译为
Sunday	星期日
Monday	星期一
Tuesday	星期二
Wednesday	星期三
Thursday	星期四
Friday	星期五
Saturday	星期六
SUN	周日
MON	周一
TUE	周二
WED	周三
THU	周四
FRI	周五
SAT	周六

空格

• 英文与非标点的中文之间需要有一个空格。【我将向你介绍一位叫 Bob 的工程师】
  • 「豆瓣 FM」等产品名词，按照官方所定义的格式书写。
• 数字与非标点的中文之间需要有一个空格。【这个系统将分为 5 个模块】
• 尽可能使用中文数词，特别是当前后都是中文时。如上面的【这个系统将分为五个模块】
• 数字与单位之间需要有一个空格，如「5 GB」而不是「5GB」，体温为 36.5 ° ，15 % 的速度提升。
• 全角标点与其他字符之间不加空格。
• 注意特殊名词的大小写：Android、iOS、iPhone、Google、Apple，无论是否在句首都应该以同样的方式写。
• 在官方文案中尽量使用中文，避免中英文混合的情况。例如「app」一般应写为「应用」或「移动应用」。品牌、产品名、人名、地名等特殊名词，如果来自英文，请使用英文以避免在不同译法间选择。

标点符号

使用规范

• 不重复使用标点符号，如错误的【！！】
• 中文语句中均使用全角符号。

  • 只有中文或中英文混排中，一律使用中文/全角标点。

  • 中英文混排中如果出现整句英文，则在这句英文中使用英文/半角标点。

  • 如果需要沿用原文中的外文缩写、外国人姓和名缩写、注册商标、产品名、公司名及国名 的缩写，则用半角 (.) 来表示该缩写。

    • 例如：const.，U.S.A.，myGengo, Inc.
      半角(.) 也可用作数字中的小数点或文件名中的分隔符。

  • 例如：123.45，config.sys

    当括号中的内容为独立的语句时，句号应被包含在括号内。

  • 例如：鲍勃在他的女朋友生日当天买了一束花作为生日礼物。（他之前从没这样做 过。）

  • 中文标点与其他字符间一律不加空格。

  • 中文文案中使用中文引号「」和『』

• 数字使用半角字符。
• 完整的英文整句、特殊名词，其内容使用半角标点。

键盘符号

• ~ ：tilde- 波浪符，Linux 用户主目录
• ` ：backtick- 反引号
• ！：exclamation mark- 惊叹号/感叹号
  • 表示强烈的感情
• @ ：at sign- 艾特符，常用于电子邮件
• #：octothorp- 井字符，常用于脚本语言的注释
• $ ：dollar sign- 美元符，bash 的变量引用
• % ：percent sign- 百分号，除法取模
• ……：省略号
  • 六个小圆点，占两个汉字的长度。 表示文中省略的地方
• ^ ：caret sigh- 插入符，正则行首，枚举逆操作
• & ：ampersand/and - 并列符,C 语言取地址
• * ：asterisk sign- 星号符，乘号
• () ：parenthesis signs/bracket：圆括号
  • 括号行文中注释性的文字，用括注形式。注释句子里某些词语的，括注紧贴在被注释词语之后；注释整个句子的，括注放在句末标点之后。
  • 补充说明
• _：understrike- 下划线，python 单独用于占位符
• ——：破折号占两个字的位置。技术文献中破折号常用于表示 注释和说明部分之前。
  • 破折号用来解 释、说明前文；连接号是把前后相关词语连成一个整体。
  • 进一步解释，接解释说明的部分
  • 表示意思的递进
  • 表示意思的转折
• - ：hyphen/minus- 连字符/减号/连接号
  • --SQL 的注释

  • —：连接号：占一个汉字的长度。

  • 四种形式（常用三种）

  • 半字线“–”（占半个字的位置）：常用于汉字与数字（字母之间）：铀–235、惠普–5000
  • 长横 ——（占两个字的位置） 常用于地名之间：北京——天津
  • 短划线 “-”（占 1/3 个字的位置）：一些外来的词汇中常用短划线： E-Mail、CD-ROM、ITU-T、8-bit、 RJ-45 插头、STM-16
  • 和浪纹“～”（占一个字的位置）。
  • 月份与日之间的连接：2020-1-1
  • 温度—压力曲线
  • - 连接两个相关的人或事物
  • ～ 时间地点数目等数值范围的起止
• +： plus sign- 加号
• = ：equals sign- 等号
• {}： curly brackets- 花括号，编程语句块，正则表示量{m,n}
• [] ：square brackets- 方括号，数组下标
• |：vertical bar- 竖号，bash 用于进程管道
• \ ：back slash- 反斜杠，常用于字符串转义
• 、：顿号：
  • 表示句中并列的词或词组之间的分隔停顿
  • 中文句子停顿使用全角顿号 、，英文句子使用半角逗号 ,
• :：colon- 冒号
  • 用在需解释的词语后面，表引出解释与说明
  • 用于接 Item list 或 Item step。
  • 全角冒号（：）常用在需要解释的词语后边，引出解释和说明。
  • 表示时间时，应使用半角冒号（:）。早上 8:00
• ;：semicolon- 分号
  • 表示复合句内部并列分句之间的停顿
• “：(double) quotation mark- 双引号
  • 表示引用的部分
  • 表示特定的称谓或需着重指出的部分
  • 表示讽刺或否定的意思
• ’ ：apostrophe/quotation mark- 单引号
• <> ：angle brackets /less than/greater than sign- 小于号大于号

  • 书名号：表示书籍、文件、报刊、文章等名称。

  • 英语中没有汉语的 《》，建议使用 <>
• ，：comma- 逗号：句子内部的一般性停顿
  • 避免一逗到底，即整个段落除了结尾，全部停顿都使用逗号。
• .：full stop/period- 句号/点号：用于陈述句末尾的停顿，在文档中常用于简单句和复合句的结尾，表示句子意思已完整。
  • 中文语句中的结尾处应该用全角句号（。）。
  • 句子末尾用括号加注时，句号应在括号之外。
• ？： question mark- 问号，三目操作符或匹配
• / ：slash- 斜杠，除号，Linux 目录分隔符

基本结构

背景
现状
需求
目标

有意思的符号

• ●

附 1- 专有名词

• 专有名词使用正确的大小写
• App：application 的缩写，是一个普通名词而不是多个单词的首字母缩写，故不可用APP
• HTML
• JavaScript
• Backbone.js
• AngularJS
• React
• GitHub
  • 错误：github/gitHub/GITHUB
• Microsoft Corporation
• Google
• Facebook
• Foursquare