【中文技术文档的写作规范_P03】如何书写标点符号和控制文档体系
通过本文，你将了解到中文技术文档中标点符号和文档体系的写法。
文章目录
- 标点符号
- 原则
- 句号
- 逗号
- 顿号
- 分号
- 引号
- 括号
- 冒号
- 省略号
- 感叹号
- 破折号
- 连接号
- 文档体系
- 结构
- 文件名
标点符号
原则
（1）中文语句的标点符号，均应该采取全角符号，这样可以与全角文字保持视觉的一致。
（2）如果整句为英文，则该句使用英文/半角标点。
（3）句号、问号、叹号、逗号、顿号、分号和冒号不得出现在一行之首。
句号
（1）中文语句的结尾处应该用全角句号（。）。
（2）句子末尾用括号加注时，句号应在括号之外。
错误：关于文件的输出，请参照第 1.3 节（见第 26 页。）正确：关于文件的输出，请参照第 1.3 节（见第 26 页）。
逗号
（1）逗号（，）表示句子内部的一般性停顿。
（2）注意避免“一逗到底”，即整个段落除了结尾，全部停顿都使用逗号。
顿号
（1）句子内部的并列词，应该用全角顿号(、) 分隔，而不用逗号，即使并列词是英语也是如此。
错误：我最欣赏的科技公司有 Google, Facebook, 腾讯, 阿里和百度等。正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。
（2）英文句子中，并列词语之间使用半角逗号（,）分隔。
例句：Microsoft Office includes Word, Excel, PowerPoint, Outlook and other components.
（3）中文句子内部的并列词，最后一个尽量使用（和）来连接，使句子读起来更加连贯，下面两个句子都可以，第二个更优。
正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里，以及百度等。正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。
分号
（1）分号（；）表示复句内部并列分句之间的停顿。
引号
（1）引用时，应该使用全角双引号（“ ”），注意前后双引号不同。
例句：许多人都认为客户服务的核心是“友好”和“专业”。
（2）引号里面还要用引号时，外面一层用双引号，里面一层用单引号（‘ ’），注意前后单引号不同。
例句：鲍勃解释道：“我要放音乐，可萨利说，‘不行！’。”
括号
（1）补充说明时，使用全角圆括号（（）），括号前后不加空格。
例句：请确认所有的连接（电缆和接插件）均安装牢固。
（2）几种括号的中英文名称。
| 英文 | 中文 | |
|---|---|---|
{ }
|
braces 或 curly brackets | 大括号 |
[ ]
|
square brackets 或 brackets | 方括号 |
< >
|
angled brackets | 尖括号 |
( )
|
parentheses | 圆括号 |
冒号
（1）全角冒号（：）常用在需要解释的词语后边，引出解释和说明。
例句：请确认以下几项内容：时间、地点、活动名称和来宾数量。
（2）表示时间时，应使用半角冒号（:）。
例句：早上 8:00
省略号
（1）省略号（……）表示语句未完、或者语气的不连续。
（2）省略号占两个汉字空间、包含六个省略点，不要使用。。。或...等非标准形式。
（3）省略号不应与“等”这个词一起使用。
错误：我们为会餐准备了香蕉、苹果、梨…等各色水果。正确：我们为会餐准备了各色水果，有香蕉、苹果、梨……正确：我们为会餐准备了香蕉、苹果、梨等各色水果。
感叹号
（1）应该使用平静的语气叙述，尽量避免使用感叹号（！）。
（2）不得多个感叹号连用，比如！！和!!!。
破折号
（1）破折号————一般用于进一步解释。
（2）破折号应占两个汉字的位置。如果破折号本身只占一个汉字的位置，那么前后应该留出一个半角空格。
例句：直觉————尽管它并不总是可靠的————告诉我，这事可能出了些问题。例句：直觉 —— 尽管它并不总是可靠的 —— 告诉我，这事可能出了些问题。
连接号
（1）连接号用于连接两个类似的词。
（2）以下场合应该使用直线连接号（-），占一个半角字符的位置。
- 两个名词的复合
- 图表编号
例句：氧化-还原反应例句：图 1-1
（3）数值范围（例如日期、时间或数字）应该使用波浪连接号（～），占一个全角字符的位置。
例句：2009 年～2011 年
注意，波浪连接号前后两个值都应该加上单位。
（4）波浪连接号也可以用汉字“至”代替。
例句：周围温度：-20°C 至 -10°C
文档体系
结构
软件手册是一部完整的书，建议采用下面的结构。
- 简介（Introduction）： [必备] [文件] 提供对产品和文档本身的总体的、扼要的说明
- 快速上手（Getting Started）：[可选] [文件] 如何最快速地使用产品
- 入门篇（Basics）： [必备] [目录] 又称”使用篇“，提供初级的使用教程
- 环境准备（Prerequisite）：[必备] [文件] 软件使用需要满足的前置条件
- 安装（Installation）：[可选] [文件] 软件的安装方法
- 设置（Configuration）：[必备] [文件] 软件的设置
- 进阶篇（Advanced)：[可选] [目录] 又称”开发篇“，提供中高级的开发教程
- API（Reference）：[可选] [目录|文件] 软件 API 的逐一介绍
- FAQ：[可选] [文件] 常见问题解答
- 附录（Appendix）：[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容
- Glossary：[可选] [文件] 名词解释
- Recipes：[可选] [文件] 最佳实践
- Troubleshooting：[可选] [文件] 故障处理
- ChangeLog：[可选] [文件] 版本说明
- Feedback：[可选] [文件] 反馈方式
下面是两个真实范例，可参考。
- Redux 手册
- Atom 手册
文件名
文档的文件名不得含有空格。
文件名必须使用半角字符，不得使用全角字符。这也意味着，中文不能用于文件名。
错误： 名词解释.md正确： glossary.md
文件名建议只使用小写字母，不使用大写字母。
错误：TroubleShooting.md正确：troubleshooting.md
为了醒目，某些说明文件的文件名，可以使用大写字母，比如README、LICENSE。
文件名包含多个单词时，单词之间建议使用半角的连词线（-）分隔。
不佳：advanced_usage.md正确：advanced-usage.md
注意，学习搬运于：https://github.com/ruanyf/document-style-guide
【中文技术文档的写作规范_P03】如何书写标点符号和控制文档体系相关推荐
- 技术文档的写作规范总结
技术文档的写作规范 1 标题 1.1 层级 标题分为四级,分别如下: 一级标题:文章的标题 二级标题:文章主要部分的大标题 三级标题:二级标题下面一级的小标题 四级标题:三级标题下面某一方面的小标题 ...
- 中文技术文档的写作规范
文章目录 一.标点符号 原则 句号 逗号 顿号 分号 引号 括号 冒号 省略号 感叹号 破折号 连接号 二.数值 半角数字 千分号 货币 数值范围 变化程度的表示法 三.段落 原则 引用 四.参考链接 ...
- 中文技术文档的写作规范-转{阮一峰}
最近我们技术老大,让我自己写一份优秀的文档,我很少写这个,但是作为技术又不得不写,几经波折之后,找到了阮一峰大神的笔记,做了参考: 标题 层级 标题分为四级. 一级标题:文章的标题 二级标题:文章主要 ...
- 中文技术文档写作规范【转载】
标题 层级 标题分为四级. 一级标题:文章的标题 二级标题:文章主要部分的大标题 三级标题:二级标题下面一级的小标题 四级标题:三级标题下面某一方面的小标题 原则 一级标题下,不能直接出现三级标题. ...
- 软件工程开发文档写作教程(05)—可行性研究报告写作规范
本文原创作者:谷哥的小弟 作者博客地址:http://blog.csdn.net/lfdfhl 本文参考资料:电子工业出版社<软件文档写作教程> 马平,黄冬梅编著 软件工程开发文档现状 一 ...
- SAP HANA中文技术文档(跟matinal学HANA)
SAP HANA中文技术文档(跟matinal学HANA) 1. 点击进入:SAP XS HANA专栏 2. 点击进入:SAP UI5上传图片 用XSJS存储在HANA中的方法 3. 点击进入: ...
- html语言中文档最前面的标记,位于HTML文档的最前面，用于向浏览器说明当前文档使用哪种HTML或XHTML标准规范的标记是（）。...
位于HTML文档的最前面,用于向浏览器说明当前文档使用哪种HTML或XHTML标准规范的标记是(). 更多相关问题 实现多地控制时,只要将起动按钮串联.将停止按钮并联即可.( ) 下列度量单位用来度量 ...
- MRD文档的写作----产品经理深入浅出课程
本篇文章是基于 多贝网刘文智老师的"产品经理深入浅出课程"撰写,下面是针对课时10的总结.该课时是针对MRD(市场需求文档)写作方法的简要介绍. 1.BRD与MRD文档的关系. ...
- Java代码规范、格式化和checkstyle检查配置文档
为便于规范各位开发人员代码.提高代码质量,研发中心需要启动代码评审机制.为了加快代码评审的速度,减少不必要的时间,可以加入一些代码评审的静态检查工具,另外需要为研发中心配置统一的编码模板和代码格式化模 ...
最新文章
- 入机器学习大坑，我需要什么样的数学水平？
- 算法笔记-异或的使用、异或算法面试题、详细解析、异或的理解与其使用规律
- 如何针对CMS系统进行SEO优化_
- .java编写一个梯形类lader_能够完成相关计算above为高_【Java】编写一个应用程序计算梯形和圆形的面积...
- 2012 BI市场（一）
- mysql联合索引的数据结构
- 质量码_在验证牛顿第二定律实验为什么要保证槽码质量m远远小于小车质量M？...
- 计算一列中某个值的个数
- PyTorch 1.0 中文官方教程：使用 Amazon AWS 进行分布式训练
- maven helper解决依赖冲突问题
- 64位程序如何调用32位dll（简单解决方案 ）
- MATLAB 2018a 安装
- 俄罗斯方块 java_java 俄罗斯方块
- air文件打包成exe
- 思科痛失瑞士电信2.5亿法郎合同
- 如何用计算机将图片整成手绘画,【新手教程】如何将手绘作品转变成电子档，并让其更像“作品”？...
- 人间烟火气 最抚凡人心
- 自然语言处理就业前景怎么样？
- 微信小程序接口调用渲染
- 自然语言处理（基于预训练模型）01FMM分词算法