跳至主要內容
09-骆驼拼写法(CamelCase)
img

注解

在英语中,依靠单词的大小写拼写复合词的做法,叫做"骆驼拼写法"(CamelCase)。比如,backColor 这个复合词,color 的第一个字母采用大写。

这种拼写法在正规的英语中是不允许的,但是在编程语言和商业活动中却大量使用。比如,sony 公司的畅销游戏机 PlayStation,play 和 station 两个词的词首字母都是大写的。


AI悦创原创...大约 2 分钟中文技术文档的写作规范中文技术文档的写作规范
08-为什么文件名要小写?

摘要

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

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

网友看见了,就提问为什么文件名要小写?

image-20230125225948933

我的回答

这是 Linux 传统,主要有两个原因,一是有些系统会自动生成大写的目录名,比如DownloadsDesktopDocuments,小写的文件名可以与系统文件区分;二是,大写需要按下 Shift 键,比较麻烦。


AI悦创原创...大约 6 分钟中文技术文档的写作规范中文技术文档的写作规范
07-参考链接

AI悦创原创...大约 2 分钟中文技术文档的写作规范中文技术文档的写作规范
06-文档体系

1. 结构

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

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

AI悦创原创...大约 2 分钟中文技术文档的写作规范中文技术文档的写作规范
05-标点符号

1. 原则

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

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

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

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

2. 句号

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

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


AI悦创原创...大约 5 分钟中文技术文档的写作规范中文技术文档的写作规范
04-数字

1. 半角数字

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

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

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

2. 千分号

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

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

AI悦创原创...大约 2 分钟中文技术文档的写作规范中文技术文档的写作规范
03-段落

1. 原则

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

2. 引用

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

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

AI悦创原创...大约 2 分钟中文技术文档的写作规范中文技术文档的写作规范
02-文本

1. 字间距

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

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

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

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

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

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

AI悦创原创...大约 6 分钟中文技术文档的写作规范中文技术文档的写作规范
01-标题

1. 层级

标题分为四级。

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

下面是示例。

# 一级标题

## 二级标题

### 三级标题

#### 四级标题

AI悦创原创...大约 2 分钟中文技术文档的写作规范中文技术文档的写作规范