技术文档规范

如题所述

第1个回答  2022-07-05
引用第三方内容时,应注明出处。

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

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

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

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

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

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

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

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

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

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

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

(1)中文语句的标点符号,均应该采取全角符号,这样可以与全角文字保持视觉的一致。

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

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

(4)点号(句号、逗号、顿号、分号、冒号)不得出现在标题的末尾,而标号(引号、括号、破折号、省略号、书名号、着重号、间隔号、叹号、问号)可以。

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

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

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

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

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

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

(3)中文句子内部的并列词,最后一个尽量使用( 和 )来连接,使句子读起来更加连贯,下面两个句子都可以,第二个更优。

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

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

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

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

(2)几种括号的中英文名称。

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

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

(1)省略号( …… )表示语句未完、或者语气的不连续。

(2)省略号占两个汉字空间、包含六个省略点,不要使用 。。。 或 ... 等非标准形式。

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

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

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

(1)破折号 ———— 一般用于进一步解释。

(2)破折号应占两个汉字的位置。如果破折号本身只占一个汉字的位置,那么前后应该留出一个半角空格。

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

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

(3)数值范围(例如日期、时间或数字)应该使用波浪连接号( ~ )或一字号( — ),占一个全角字符的位置。

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

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

参考范例:

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

文件名必须使用半角字符,不得使用全角字符、中文。

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

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

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

https://github.com/ruanyf/document-style-guide/blob/master/docs/reference.md
https://github.com/ruanyf/document-style-guide
http://www.ruanyifeng.com/blog/2017/02/filename-should-be-lowercase.html

内容转自: https://www.ruanyifeng.com/blog/2016/10/document_style_guide.html
相似回答