那些你可能会忽略的写作规范

八月 19, 2021 3734
  • 写在前面：在 GitHub 发现了这一有趣的仓库，选取部分内容，整理成文，希望能够提醒自己保持优雅的写作习惯。
  • License：公共领域（public domain）

中文和英文排列

字间距

（1）全角中文字符与半角英文字符之间，应有一个半角空格。

1
2
3
错误：本文介绍如何快速启动Windows系统。

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

（2）全角中文字符与半角阿拉伯数字之间，有没有半角空格都可，但必须保证风格统一，不能两种风格混杂。

1
2
3
正确：2011年5月15日，我订购了5台笔记本电脑与10台平板电脑。

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

半角的百分号，视同阿拉伯数字。

1
2
3
正确：今年我国经济增长率是6.5%。

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

（3）英文单位若不翻译，单位前的阿拉伯数字与单位符号之间，应留出适当的空隙。

1
2
3
例1：一部容量为 16 GB 的智能手机

例2：1 h = 60 min = 3,600 s

（4）半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。

1
2
3
错误：他的电脑是 MacBook Air 。

正确：他的电脑是 MacBook Air。

句子

（1）避免使用长句。

不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。

1
2
3
错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。

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

逗号分割的长句，总长度不应该超过 100 字或者正文的 3 行。

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

1
2
3
并列句：他昨天生病了，没有参加会议。

复合句：那个昨天生病的人没有参加会议。

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

1
2
3
错误：请确认没有接通装置的电源。

正确：请确认装置的电源已关闭。

（4）避免使用双重否定句。

1
2
3
错误：没有删除权限的用户，不能删除此文件。

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

写作风格

（1）尽量不使用被动语态，改为使用主动语态。

1
2
3
错误：假如此软件尚未被安装，

正确：假如尚未安装这个软件，

（2）不使用非正式的语言风格。

1
2
3
错误：Lady Gaga 的演唱会真是酷毙了，从没看过这么给力的表演！！！

正确：无法参加本次活动，我深感遗憾。

（3）不使用冷僻、生造或者文言文的词语，而要使用现代汉语的常用表达方式。

1
2
3
错误：这是唯二的快速启动的方法。

正确：这是仅有的两种快速启动的方法。

（4）用对“的”、“地”、“得”。

1
2
3
4
5
6
7
8
她露出了开心的笑容。
（形容词＋的＋名词）

她开心地笑了。
（副词＋地＋动词）

她笑得很开心。
（动词＋得＋副词）

（5）使用代词时（比如“其”、“该”、“此”、“这”等词），必须明确指代的内容，保证只有一个含义。

1
2
3
错误：从管理系统可以监视中继系统和受其直接控制的分配系统。

正确：从管理系统可以监视两个系统：中继系统和受中继系统直接控制的分配系统。

（6）名词前不要使用过多的形容词。

1
2
3
错误：此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。

正确：此设备必须在技师的指导下使用，且指导技师必须接受过由本公司举办的正式设备培训。

英文处理

（1）英文原文如果使用了复数形式，翻译成中文时，应该将其还原为单数形式。

1
2
3
英文：⋯information stored in random access memory (RAMs)⋯

中文：……存储在随机存取存储器（RAM）里的信息……

（2）外文缩写可以使用半角圆点(.)表示缩写。

1
2
U.S.A.
Apple, Inc.

（3）表示中文时，英文省略号（⋯）应改为中文省略号（……）。

1
2
3
英文：5 minutes later⋯

中文：5 分钟过去了……

（4）英文书名或电影名改用中文表达时，双引号应改为书名号。

1
2
3
英文：He published an article entitled "The Future of the Aviation".

中文：他发表了一篇名为《航空业的未来》的文章。

（5）第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可。

1
IOC（International Olympic Committee，国际奥林匹克委员会）。这样定义后，便可以直接使用“IOC”了。

（6）专有名词中每个词第一个字母均应大写，非专有名词则不需要大写。

1
2
3
“American Association of Physicists in Medicine”（美国医学物理学家协会）是专有名词，需要大写。

“online transaction processing”（在线事务处理）不是专有名词，不应大写。

文字和数字排列

半角数字

阿拉伯数字一律使用半角形式，不得使用全角形式。

1
2
3
错误：这件商品的价格是１０００元。

正确：这件商品的价格是 1000 元。

千分号

数值为千位以上，应添加千分号（半角逗号）。

1
XXX 公司的实收资本为 ￥1,258,000 人民币。

对于 4 位的数值，千分号是选用的，比如1000和1,000都可以接受。对于 4 位以上的数值，应添加千分号。

货币

货币应为阿拉伯数字，并在数字前写出货币符号，或在数字后写出货币中文名称。

1
2
$1,000
1,000 美元

英文的货币名称，建议参考国际标准 ISO 4217。

数值范围

表示数值范围时，用波浪线（～）或一字线（—）连接。参见《标点符号》一节的“连接号”部分。

带有单位或百分号时，两个数字建议都要加上单位或百分号。

1
2
3
132kg～234kg

67%～89%

变化程度的表示法

数字的增加要使用“增加了”、“增加到”。“了”表示增量，“到”表示定量。

1
2
3
4
5
增加到过去的两倍
（过去为一，现在为二）

增加了两倍
（过去为一，现在为三）

数字的减少要使用“降低了”、“降低到”。“了”表示增量，“到”表示定量。

1
2
3
4
5
降低到百分之八十
（定额是一百，现在是八十）

降低了百分之八十
（原来是一百，现在是二十）

不能用“降低 N 倍”或“减少 N 倍”的表示法，要用“降低百分之几”或“减少百分之几”。因为减少（或降低）一倍表示数值原来为一百，现在等于零。

说明文档的结构

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

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

下面是两个真实范例，可参考。

文件命名规则

文档的文件名不得含有空格。

文件名必须使用半角字符，不得使用全角字符。这也意味着，中文不能用于文件名。

1
2
3
错误：名词解释.md

正确：glossary.md

文件名建议只使用小写字母，不使用大写字母。

1
2
3
错误：TroubleShooting.md

正确：troubleshooting.md

为了醒目，某些说明文件的文件名，可以使用大写字母，比如README、LICENSE。

文件名包含多个单词时，单词之间建议使用半角的连词线（-）分隔。

1
2
3
不佳：advanced_usage.md

正确：advanced-usage.md


\ E.O.F \

Ref

Changlog

  • 210819 init
查看评论