余晖落尽暮晚霞,黄昏迟暮远山寻
本站
当前位置:网站首页 > 编程知识 > 正文

不再恐惧写技术文档:云栖社区中文技术文档写作规范

xiyangw 2022-11-25 12:52 138 浏览 0 评论

标题

1. 层级

标题分为四级。

  • 一级标题:文章的标题

  • 二级标题:文章主要部分的大标题

  • 三级标题:二级标题下面一级的小标题

  • 四级标题:三级标题下面某一方面的小标题

2. 层级

  • 一级标题下,不能直接出现三级标题。

  • 标题要避免孤立编号(即同级标题只有一个)。

  • 下级标题不重复上一级标题的内容。

  • 谨慎使用四级标题,尽量避免出现,保持层级的简单和防止出现过于复杂的章节。如果三级标题下有并列性的内容,建议只使用项目列表(Item list)。

文本

字间距

全角中文字符与半角英文字符之间,应有一个半角空格。

错误:本文介绍如何快速启动Windows系统。

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

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

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

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

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

英文单位若不翻译,单位前的阿拉伯数字与单位间不留空格。

错误:一部容量为 16 GB 的智能手机

正确:一部容量为 16GB 的智能手机

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

错误:他的电脑是 MacBook Air 。

正确:他的电脑是 MacBook Air。

句子

  • 避免使用长句。一个句子建议不超过 100 字或者正文的 3 行。

  • 尽量使用简单句和并列句,避免使用复合句。

写作风格

尽量不使用被动语态,改为使用主动语态。

错误:假如此软件尚未被安装,

正确:假如尚未安装这个软件,

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

错误:Lady Gaga 的演唱会真是酷毙了,从没看过这么给力的表演!!!

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

用对“的”、“地”、“得”。

她露出了开心的笑容。

(形容词+的+名词)

她开心地笑了。

(副词+地+动词)

她笑得很开心。

(动词+得+副词)

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

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

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

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

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

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

单个句子的长度尽量保持在 20 个字以内;20~29 个字的句子,可以接受;30~39 个字的句子,语义必须明确,才能接受;多于 40 个字的句子,在任何情况下都不能接受。

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

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

同样一个意思,尽量使用肯定句表达,不使用否定句表达。

错误:请确认没有接通装置的电源。

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

避免使用双重否定句。

错误:没有删除权限的用户,不能删除此文件。

英文处理

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

英文:?information stored in random access memory (RAMs)?

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

U.S.A.

表示中文时,英文省略号(?)应改为中文省略号(……)。

英文:5 minutes later?

英文书名或电影名改用中文表达时,双引号应改为书名号。

英文:He published an article entitled "The Future of the Aviation".

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

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

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

“American Association of Physicists in Medicine”(美国医学物理学家协会)是专有名词,需要大写。

段落

原则

  • 一个段落只能有一个主题,或一个中心句子。

  • 段落的中心句子放在段首,对全段内容进行概述。后面陈述的句子为核心句服务。

  • 一个段落的长度不能超过七行,最佳段落长度小于等于四行。

  • 段落的句子语气要使用陈述和肯定语气,避免使用感叹语气。

  • 段落之间使用一个空行隔开。

  • 段落开头不要留出空白字符。

引用

引用第三方内容时,应注明出处。

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

如果是全篇转载,请在全文开头显著位置注明作者和出处,并链接至原文。

本文转载自 WikiQuote

使用外部图片时,必须在图片下方或文末标明来源。

本文部分图片来自 Wikipedia

数值

半角数字

数字一律使用半角形式,不得使用全角形式。

错误: 这件商品的价格是1000元。

千分号

数值为千位以上,应添加千分号(半角逗号)。

XXX 公司的实收资本为 RMB1,258,000。

对于 4 ~ 6 位的数值,千分号是选用的,比如1000和1,000都可以接受。对于7位及以上的数值,千分号是必须的。

多位小数要从小数点后从左向右添加千分号,比如4.234,345。

货币

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

$1,000

数值范围

表示数值范围时,用~连接。参见《标点符号》一节的“连接号”部分。

带有单位或百分号时,两个数字都要加上单位或百分号,不能只加后面一个。

错误:132~234kg

变化程度的表示法

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

增加到过去的两倍

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

降低到百分之八十

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

标点符号

原则

  • 中文语句的标点符号,均应该采取全角符号,这样可以保证视觉的一致。

  • 如果整句为英文,则该句使用英文/半角标点。

  • 句号、问号、叹号、逗号、顿号、分号和冒号不得出现在一行之首。

句号

中文语句中的结尾处应该用全角句号(。)。

句子末尾用括号加注时,句号应在括号之外。

错误:关于文件的输出,请参照第 1.3 节(见第 26 页。)

逗号

逗号,表示句子内部的一般性停顿。

注意避免“一逗到底”,即整个段落除了结尾,全部停顿都使用逗号。

顿号

句子内部的并列词,应该用全角顿号(、) 分隔,而不用逗号,即使并列词是英语也是如此。

错误:我最欣赏的科技公司有 Google, Facebook, 腾讯, 阿里和百度等。

英文句子中,并列词语之间使用半角逗号(,)分隔。

例句:Microsoft Office includes Word, Excel, PowerPoint, Outlook and other components.

分号

分号;表示复句内部并列分句之间的停顿。

引号

引用时,应该使用全角双引号(“ ”),注意前后双引号不同。

例句:许多人都认为客户服务的核心是“友好”和“专业”。

引号里面还要用引号时,外面一层用双引号,里面一层用单引号(‘ ’),注意前后单引号不同。

例句:鲍勃解释道:“我要放音乐,可萨利说,‘不行!’。”

圆括号

补充说明时,使用全角圆括号(),括号前后不加空格。

例句:请确认所有的连接(电缆和接插件)均安装牢固。

冒号

全角冒号(:)常用在需要解释的词语后边,引出解释和说明。

例句:请确认以下几项内容:时间、地点、活动名称,以及来宾数量。

表示时间时,应使用半角冒号(:)。

例句:早上 8:00

省略号

省略号……表示语句未完、或者语气的不连续。它占两个汉字空间、包含六个省略点,不要使用。。。或...等非标准形式。

省略号不应与“等”这个词一起使用。

错误:我们为会餐准备了香蕉、苹果、梨…等各色水果。

感叹号

应该使用平静的语气叙述,尽量避免使用感叹号!。

不得多个感叹号连用,比如!!和!!!。

破折号

破折号————一般用于做进一步解释。破折号应占两个汉字的位置。

例句:直觉————尽管它并不总是可靠的————告诉我,这事可能出了些问题。

连接号

连接号用于连接两个类似的词。

以下场合应该使用直线连接号(-),占一个半角字符的位置。

  • 两个名词的复合

  • 图表编号

  • 例句:氧化-还原反应

以下场合应该使用波浪连接号(~),占一个全角字符的位置。

  • 数值范围(例如日期、时间或数字)

例句:2009 年~2011 年

注意,波浪连接号前后两个值都应该加上单位。

波浪连接号也可以用汉字“至”代替。

例句:周围温度:-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

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

错误:TroubleShooting.md

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

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

不佳:advanced_usage.md

参考链接

  • 产品手册中文写作规范, by 华为

  • 写作规范和格式规范, by DaoCloud

  • 技术写作技巧在日汉翻译中的应用, by 刘方

  • 简体中文规范指南, by lengoo

  • 文档风格指南, by LeanCloud

  • 豌豆荚文案风格指南, by 豌豆荚

  • 中文文案排版指北, by sparanoid

  • 中文排版需求, by W3C

  • 为什么文件名要小写?, by 阮一峰


相关推荐

数控系统常见术语详解,机加工人士必备资料
数控系统常见术语详解,机加工人士必备资料

增量编码器(Incrementpulsecoder)回转式位置测量元件,装于电动机轴或滚珠丝杠上,回转时发出等间隔脉冲表示位移量。由于没有记忆元件,故不能准...

2023-09-24 17:42 xiyangw

功、功率、扭矩的关系

功=功率×时间work=power×timeW=P×T功=力×距离work=force×lengthW=F×LP×T=F×LP=F×L/T=F×V(velocity)具体到电机输出轴上,圆...

Wi-Fi协议(802.11 )常见专业术语汇总
Wi-Fi协议(802.11 )常见专业术语汇总

Wi-Fi协议(802.11)常见专业术语汇总AP(Accesspoint的简称,即访问点,接入点):是一个无线网络中的特殊节点,通过这个节点,无线网络中的...

2023-09-24 17:41 xiyangw

不需要策略模式也能避免满屏if/else
不需要策略模式也能避免满屏if/else

满屏if/elsejava复制代码publicstaticvoidmain(String[]args){inta=1;if...

2023-09-24 17:41 xiyangw

喜极而泣,我终于干掉了该死的 if-else
喜极而泣,我终于干掉了该死的 if-else

推荐阅读:面试淘宝被Tomcat面到“自闭”,学习这份文档之后“吊打”面试官刷完spring+redis+负载均衡+netty+kafka面试题,再去面试BAT...

2023-09-24 17:40 xiyangw

Python中使用三元运算符简化if-else语句
Python中使用三元运算符简化if-else语句

Python是一种极简主义的编程语言,相比其他编程语言,在多个地方简化了代码的写法,可以让我们用更少的时间更简洁地完成工作。以赋值运算符为例:a=a+b简化...

2023-09-24 17:40 xiyangw

雅思课堂 | 雅思口语写作句型第二讲
雅思课堂 | 雅思口语写作句型第二讲

纯干货,无废话用最少的时间学最制胜的内容!泡图书馆泡不过学霸?碎片时间也能弯道超车!向着雅思8分行动起来吧!雅思口语写作句型1.Ipreferseeing...

2023-09-24 17:39 xiyangw

设计模式(三)——简单的状态模式代替if-else
设计模式(三)——简单的状态模式代替if-else

博主将会针对Java面试题写一组文章,包括J2ee,SQL,主流Web框架,中间件等面试过程中面试官经常问的问题,欢迎大家关注。一起学习,一起成长。前言大多数开...

2023-09-24 17:38 xiyangw

如何优化代码中大量的if/else,switch/case?

前言随着项目的迭代,代码中存在的分支判断可能会越来越多,当里面涉及到的逻辑比较复杂或者分支数量实在是多的难以维护的时候,我们就要考虑下,有办法能让这些代码变得更优雅吗?正文使用枚举这里我们简单的定义一...

优秀程序员早就学会用“状态模式”代替if-else了
优秀程序员早就学会用“状态模式”代替if-else了

2020年已经进入倒计时了,大家立好的flag完成了吗?2020实“鼠”不易,希望2021可以“牛”转乾坤。简介状态模式是行为型设计模式的一种。其设计理念是当对...

2023-09-24 17:37 xiyangw

用Select Case语句对执行多条件进行控制
用Select Case语句对执行多条件进行控制

今日的内容是"VBA之EXCEL应用"的第六章"条件判断语句(If...Then...Else)在VBA中的利用"。这讲是第三节...

2023-09-24 17:37 xiyangw

c#入门教程(四)条件判断if else

条件判断,是编程里常用的判断语句,比如某个代码如果满足条件就执行a代码块否则就执行b代码块。案例1:inti=2*5;if(a>0){执行a代码块}elseif(a<0){执行b代码块...

每日学编程之JAVA(十一)—条件语句(if……else)

一个if语句包含一个布尔表达式和一条或多条语句。如果布尔表达式的值为true,则执行if语句中的代码块,否则执行if语句块后面的代码。if语句后面可以跟else语句,当if语句...

不需要策略模式也能避免满屏if/else

除了使用策略模式以外,还可以使用其他设计模式来避免满屏if/else的问题。以下是一些可能的解决方案:工厂模式:将if/else语句移到工厂类中,由工厂类负责创建对象。这样可以将if/else语句从客...

围绕ifelse与业务逻辑的那些梗
围绕ifelse与业务逻辑的那些梗

ifelse很重要,几乎是程序员编程核心,业务逻辑与规则也通过ifelse体现出来,语句简单但是背后文章很大,先看几则幽默图:1.也许默认使用returnf...

2023-09-24 17:36 xiyangw

取消回复欢迎 发表评论: