文档风格

Table of Contents

→ 本篇完全以阮一峰老师的 《中文技术文档的写作规范》 为基础进行扩展,仅供学习参考。

简介

本文旨在规范文档写作风格,在系统层面保持信息表达的准确性和渐进性,总体符合现行通用标准,以减少隐性无用的阅读精力投入。

文档体系

结构

ISBA AFA
Introduction Started Basics Advanced API FAQ Appendix

WHM - What? How? More?

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

具体可以参考下 Redux 手册 的结构。

文件名

为了使文件具备更好的平台兼容性、规范以及方便输入,对文件名做以下约定:

  • 文件名不允许含有空格;
  • 建议使用英文半角字符;
  • 建议只使用小写字母(某些说明文件,如 README 、LICENSE 除外);
  • 文件名包含多个单词时,单词之间用半角的连词线 - 分隔。
✘ hello world.md

✘ 名词解释.md
✔ glossary.md

✘ TroubleShooting.md
✔ troubleshooting.md
✔ REAMDE

✘ advanced_usage.md
✔ advanced-usage.md

标题

层级

标题分为四级,如下:

  • 一级标题:文章的标题;
  • 二级标题:文章主要部分的大标题;
  • 三级标题:二级标题下面一级的小标题;
  • 四级标题:三级标题下面某一方面的小标题。

原则

标题应遵循以下原则:

  • 一级标题下,不能直接出现三级标题;
  • 标题要避免孤立编号(即同级标题只有一个);
  • 下级标题不重复下一级标题的名字;
  • 谨慎使用四级标题,尽量避免出现,保持层级的简单。

文本

字间距

  • 全角中文字符与英文字符之间,应有一个半角空格;
  • 全角中文字符与阿拉伯数字之间,有没有半角空格皆可,但必须保证风格统一(建议使用空格);
  • 英文单位若不翻译,单位前的阿拉伯数字与单位符号之间,应留出适当的空隙;
  • 半角英文字符和半角阿拉伯数字,与全角符号之间不留空格。
✘ 本文介绍如何快速启动Windows系统。
✔ 本文介绍如何快速启动 Windows 系统。

✔ 2011年5月15日,我订购了5台笔记本电脑与10台平板电脑。
✔ 2011 年 5 月 15 日,我订购了 5 台笔记本电脑与 10 台平板电脑。

✔ 一部容量为 16 GB 的智能手机
✔ 1 h = 60 min = 3,600 s

✘ 他的电脑是 MacBook Air 。
✔ 他的电脑是 MacBook Air。

句子

  • 单句应避免使用长句(尽量保持在 30 个字符以内);
  • 尽量使用简单句和并列句,避免使用复合句;
  • 同一个意思,尽量使用肯定句,不使用否定句表达;
  • 避免使用双重否定句。
✘ 本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。
✔ 本产品适用于多种体系结构。无论是由一台服务器(单一节点结构),还是由多台服务器(并行处理结构)进行动作控制,均可以使用本产品。

✘ 复合句:那个昨天生病的人没有参加会议。
✔ 并列句:他昨天生病了,没有参加会议。

✘ 请确认没有接通装置的电源。
✔ 请确认装置的电源已关闭。

✘ 没有删除权限的用户,不能删除此文件。
✔ 用户必须拥有删除权限,才能删除此文件。

写作风格

  • 尽量不使用被动语态,改为使用主动语态;
  • 不使用非正式的语言风格;
  • 不使用冷僻、生造或者文言文的词语,而要使用现代汉语的常用表达方式;
  • 用对“的、地、得”;
  • 使用代词时(比如“其、该、此、这”等词),必须明确指代的内容,保证只有一个含义;
  • 名词前不要使用过多的形容词。
✘ 假如此软件尚未被安装,
✔ 假如尚未安装这个软件,

✘ Lady Gaga 的演唱会真是酷毙了,从没看过这么给力的表演!!!
✔ 无法参加本次活动,我深感遗憾。

✘ 这是唯二的快速启动的方法。
✔ 这是仅有的两种快速启动的方法。

✔ 她露出了开心的笑容。
(形容词+的+名词)
✔ 她开心地笑了。
(副词+地+动词)
✔ 她笑得很开心。
(动词+得+副词)

✘ 从管理系统可以监视中继系统和受其直接控制的分配系统。
✔ 从管理系统可以监视两个系统:中继系统和受中继系统直接控制的分配系统。

✘ 此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。
✔ 此设备必须在技师的指导下使用,且指导技师必须接受过由本公司举办的正式设备培训。

英文处理

  • 英文原文如果使用了复数形式,翻译成中文时,应该将其还原为单数形式;
  • 外文缩写可以使用半角加点 . 表示缩写;
  • 表示中文时,英文省略号 ... 应改为中文省略号 ……
  • 英文书名或电影名改用中文表达时,双引号应也改为书名号;
  • 第一次出现英文词汇量,在括号中给出中文标注;
  • 专有名词中每个词第一个字母应大写,非专有名词不需要大写。
✔ ⋯information stored in random access memory (RAMs)⋯
✔ ……存储在随机存取存储器(RAM)里的信息……

✔ U.S.A.
✔ Apple, Inc.

✔ 5 minutes later⋯
✔ 5 分钟过去了……

✔ He published an article entitled "The Future of the Aviation".
✔ 他发表了一篇名为《航空业的未来》的文章。

✔ IOC(International Olympic Committee,国际奥林匹克委员会)。这样定义后,便可以直接使用“IOC”了。

✔ “American Association of Physicists in Medicine”(美国医学物理学家协会)是专有名词,需要大写。
✔ “online transaction processing”(在线事务处理)不是专有名词,不应大写。

段落

原则

  • 一个段落只能有一个主题,或一个中心句子;
  • 段落的中心句子放在段首,对全段内容时行概述,后面陈述的句子为核心句服务;
  • 一个段落的长度不能超过七行,最佳段落长度小于等于四行;
  • 段落的句子语气要使用陈述语气和肯定语气,避免使用感叹语气;
  • 段落之间使用一个空行隔开;
  • 段落开关不要留出空白字符。

引用

  • 引用第三方内容时,应注明出处;
  • 如果是全篇转载,请在全文开头显著位置注明作者和出处,并链接至原文;
  • 使用外部图片时,必须在图片下方或文末标明来源。
✔ One man’s constant is another man’s variable. — Alan Perlis

✔ 本文转载自 WikiQuote

✔ 本文部分图片来自 Wikipedia

数值

  • 阿拉伯数字一律使用半角形式,不得使用全角形式;
  • 数值为千位以上,应添加千分号(半角逗号);
  • 表示数值范围时,用 ~- 连接。
✘ 这件商品的价格是1000元。
✔ 这件商品的价格是 1000 元。

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

✔ 132kg~234kg 之间的在 67%~89% 范围内。

标点符号

中文中用,西文西用。

小结

写作风格,既然是风格,便不可能绝对相同,都具备一定的使用场景,不必过于拘泥。

行文风格规范,也完全没有必要死记硬背,它是一个渐进的、不断完善的过程。当你需要它的时候,你就会注意到它!简单来说,就是按需取用。

结构清晰渐进,标题不孤不繁;
文本中西分用,段落述长概短;
数值半角分隔,标点中西区分。

Date: 2020-05-19 Tue 11:40

Author: Jack Liu

Created: 2020-05-19 Tue 16:23

Validate