diff --git a/zh-cn/contribute/style-guide/Readme-CN.md b/zh-cn/contribute/style-guide/Readme-CN.md new file mode 100644 index 0000000000000000000000000000000000000000..2a80e2a32cde98f8d5e5898765152df9a8d090dc --- /dev/null +++ b/zh-cn/contribute/style-guide/Readme-CN.md @@ -0,0 +1,6 @@ +# OpenHarmony开发者文档风格指南 + +- [关于本指南](style-guide-overview.md) +- [语言风格](style-guide-language-style.md) +- [文档结构](style-guide-document-structure.md) +- [内容元素](style-guide-content-elements.md) diff --git a/zh-cn/contribute/style-guide/figures/code-block-example.png b/zh-cn/contribute/style-guide/figures/code-block-example.png new file mode 100644 index 0000000000000000000000000000000000000000..a9516e7ffbede5b0d135ee88ecf8881d8475c0ae Binary files /dev/null and b/zh-cn/contribute/style-guide/figures/code-block-example.png differ diff --git a/zh-cn/contribute/style-guide/figures/heading-edit-style.png b/zh-cn/contribute/style-guide/figures/heading-edit-style.png new file mode 100644 index 0000000000000000000000000000000000000000..560254fc93d8b92c2cffa13d8209cd5a5e6c8763 Binary files /dev/null and b/zh-cn/contribute/style-guide/figures/heading-edit-style.png differ diff --git a/zh-cn/contribute/style-guide/figures/heading-preview-style.png b/zh-cn/contribute/style-guide/figures/heading-preview-style.png new file mode 100644 index 0000000000000000000000000000000000000000..5f817d6bf416ff11969dac1eb0a519ba1698a0ee Binary files /dev/null and b/zh-cn/contribute/style-guide/figures/heading-preview-style.png differ diff --git a/zh-cn/contribute/style-guide/figures/recommended-colors.png b/zh-cn/contribute/style-guide/figures/recommended-colors.png new file mode 100644 index 0000000000000000000000000000000000000000..b1b56147bac00df0855e3cc7d63c563c032d7bd6 Binary files /dev/null and b/zh-cn/contribute/style-guide/figures/recommended-colors.png differ diff --git a/zh-cn/contribute/style-guide/figures/screenshot-example.png b/zh-cn/contribute/style-guide/figures/screenshot-example.png new file mode 100644 index 0000000000000000000000000000000000000000..96d7f0f334e1f820f25806c1131e0eaf1f9ca2b0 Binary files /dev/null and b/zh-cn/contribute/style-guide/figures/screenshot-example.png differ diff --git a/zh-cn/contribute/style-guide/style-guide-content-elements.md b/zh-cn/contribute/style-guide/style-guide-content-elements.md new file mode 100644 index 0000000000000000000000000000000000000000..918f34b1464ccdd8059892b5e1b0c1f0a2d2ee0e --- /dev/null +++ b/zh-cn/contribute/style-guide/style-guide-content-elements.md @@ -0,0 +1,377 @@ +# 内容元素 + + +## 项目列表 + +【规则】无序列表统一使用破折号（-）并紧跟一个空格，有序列表统一使用数字并紧跟一个英文句点和一个空格。 + +| **正例** | **反例** | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| \- 无序列表第一项
\- 无序列表第二项
\- 无序列表第三项
1. 有序列表第一项
2. 有序列表第二项
3. 有序列表第三项 | \- 无序列表第一项
\* 无序列表第二项
\+ 无序列表第三项
1) 有序列表第一项
2) 有序列表第二项
3) 有序列表第三项 | + +【规则】列表项采用相似结构、统一句式，例如，全部采用短语或句子。 + +| **正例** | **反例** | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| 播放事件回调类型，支持的事件包括 `'play'|'stop'|'dataLoad'` ：
- `play`：完成play()调用，音频开始播放，触发该事件。
- `stop`：完成stop()调用，音频停止播放，触发该事件。
- `dataLoad`：完成音频数据加载后触发该事件，即src属性设置完成后触发该事件。 | 播放事件回调类型，支持的事件包括 `'play'|'stop'|'dataLoad'` ：
- `play`：音频开始播放时触发。
- `stop`：音频停止事件。
- `dataLoad`：完成音频数据加载后触发该事件，即src属性设置完成后触发。 | + +【规则】当项目列表项是术语、短语时，句末统一不加标点符号；当项目列表项是句子时，句末统一加句号。 + +| 正例 | 反例 | +| -------- | -------- | +| 支持格式包括：
- video/h263
- audio/mp4a-latm | 无 | + +【建议】一个项目列表的列表项建议为2～9项。 + +【建议】只有一项的列表和前后上下文的内容合并，采用正文样式。 + +【建议】列表的层级不超过2层，包括有序列表和无序列表的组合。 + + +## 表格 + +【规则】表格至少为两行两列。 + +【规则】相同类型的表标题、表头，风格保持一致，采用名词或名词词组的形式。 + +同样对参数进行说明的表，不应出现“参数说明”、“参数解释”、“参数含义”、“参数意义”等不同的表头内容，需要全文保持统一。 + +【规则】同一列信息的表达方式一致，句末的标点符号要保持一致。 + +- 如果表格一列全部为短语，句末不加句号。 + +- 如果表格一列全是句子或同时存在句子和短语，句末统一加句号。 + +【规则】不出现空白的单元格，无内容单元区分“无”和“不涉及”。如果大量的“不涉及”导致表格中重要信息不突出，则采用“－”表示“不涉及”。 + +【规则】Markdown语法不支持合并单元格，遇到对应场景需要进行表格拆分或将行内容直接合并。 + +【规则】表格内容默认使用左对齐。 + + +## 图片 + + +### 图片总体要求 + +【规则】严禁使用无版权图片。如无法确认是否拥有某图片的永久版权，请不要使用，改用自行绘制、拍摄的图片。 + +【规则】图片应清晰展示目标信息，避免使用人工合成或像素低的图片。 + +【规则】图片尺寸不能过大，在页面放大比例为100%的情况下，不能大于一屏。 + +【规则】图片禁止通过URL地址引用，需要取到本地引用。 + +【规则】图片命名规范： + +- 由字母、数字、中划线“-”组成。 + +- 语义化，图片名能体现图片展示内容的核心名词/动词，可从图标题、上下文、展示内容或目的等维度获取，原则上不超过4个英文单词。例如：typical-service-view.png。 + +- 同一文件夹下，图片名不允许重复。 + +【建议】为避免图片过大或过小，影响文档阅读体验，建议的图片宽度为：大图600磅（约800px）、中图360磅（约480px）、小图200磅（约260px）。 + + +### 绘图 + +【建议】字号：中英文正常字号均采用10.5pt（14px）。中文字号下限为9pt（12px），英文字号下限为8pt（11px）。 + +【建议】优先使用灰色、蓝色两套配色，一张图建议不超过3套配色。 + +建议配色如下： + +![建议配色](figures/recommended-colors.png) + + +### 截图 + +【规则】界面截图边缘应完整、清晰。没有明显边界的，应手动添加浅灰色外边框（RGB：217/217/217）。 + +【规则】截图中，不要截取非必要信息，如桌面上的其他图标、工具栏等。 + +【规则】截图中，不能包含敏感信息，如私人邮箱、公网IP地址等。 + +![截图示例](figures/screenshot-example.png) + +【建议】截图中需要突出显示的关键信息，统一使用1px的蓝色（RGB：37/79/247）线框框选。框选时，应使关键信息位于框线中心位置，且框线尽量贴近关键信息边缘。 + + +## 提示与说明 + +【规则】当需要向用户提供区别于正文的重要提示或补充说明信息时，请使用以下信息标识符，以示强调。 + +| 标识符 | 用途/含义 | 典型使用场景举例 | +| -------- | -------- | -------- | +| 说明
（英文为：Note） | 提供帮助提示或有用的参考信息。 | - 支撑开发者做出决策的信息（参数选取原则、系统实现机制补充说明等）
- 可提升开发效率的信息
- 版本差异说明
- 依赖说明
- 相关参考信息 | +| 注意
（英文为：Caution） | 如未按该注意事项操作，可能会导致任务中断或结果异常，但是可恢复。 | - 导致功能异常
- 导致测试失败
- 影响系统开销/系统性能
- 特性约束限制/版本要求
- 影响应用成功安装
- 导致进程攻击
- 导致内存访问错误或内存损坏
- 导致安全类问题（如数据安全/设备安全/帐号安全等）
- 导致稳定性问题
- 导致兼容性问题
- 影响应用分发
- 影响设备安全等级评估
- 影响用户体验（影响可用带宽、服务使用、电池续航、对应用信任度等） | +| 警告
（英文为：Warning） | 如未按该警告内容操作，可能会导致结果异常，且不可恢复。 | - 导致用户数据丢失
- 导致硬件损坏 | + +【规则】使用Markdown的引用语法“>”对提示或补充信息进行描述。 + +> **说明：** + +> 该接口从API Version 7 开始不再维护，建议使用newMethod替代。 + +【规则】提示或补充信息中不能包含表格和图片（图标除外）。 + +【规则】提示或补充信息内容不能过长，建议内容在一个段落范围内。 + +【规则】“注意”及更高级别的提示信息统一放在正文或步骤之前，用来提前警示相关事项，提醒用户避免损失。 + +【规则】禁止滥用“说明”。如果Web页面中一屏幕“说明”的数目超过2个，请考虑将其改为正文信息。 + + +## 链接 + + +### 链接规则 + +当需要参考其他手册内容、本手册中其他章节内容时，可添加到对应内容的链接。 + +【规则】跨文档或跨章节的链接，采用统一表达“请参见xxx”。 + +【规则】使用动词“单击”表示对网页类链接的操作。 + +【建议】对于内容很少（小于100字）但必须参考的内容，建议直接重述该内容；对于参考内容很多且不便重述的内容，添加链接。 + +【建议】一篇文档中应避免出现过多的交叉引用和外部链接。 + + +### 链接样式 + +【规则】将链接URL写入内容，而不是直接在页面中暴露URL地址。 + +- 链接到其他手册、页面内容：\[术语](glossary/glossary.md) + +- 链接到本页面内其他内容段落：\[FAQ](#faq) + +- 链接到其他站点：\[示例](www.example.com) + + | **正例** | **反例** | + | -------- | -------- | + | 请参见\[OpenHarmony开源项目](https://gitee.com/openharmony) | OpenHarmony开源项目请参见https://gitee.com/openharmony | + + +## 术语及缩略语 + +【规则】术语/缩略语名称要同“[OpenHarmony术语表](https://gitee.com/openharmony/docs/blob/master/zh-cn/glossary.md)”保持一致，且全文统一。 + +【规则】对于“[OpenHarmony术语表](https://gitee.com/openharmony/docs/blob/master/zh-cn/glossary.md)”中未涵盖的行业通用术语/缩略语（如IP，MAC等），要同国际、国家、行业标准中的名称保持一致。 + +【规则】禁止随意缩写英文单词，自创缩略语。 + +【规则】除行业通用术语/缩略语外，正文中出现的所有术语/缩略语都需要在术语表中给出解释。 + +【规则】中文文档中，缩略语全称中对应的字母大写。 + +【建议】一篇文档中某缩略语首次出现的位置（标题和表头除外），提供英文全称，可选提供中文全称。 + +【建议】开发板名称、设备名称等不作为术语或缩略语，不在术语表中体现。建议在文档中单独以表格或其他形式介绍。 + + +## 单位符号 + +【规则】用单位符号代替汉字名称。例如：mm代替毫米。 + +【规则】不能在组合单位中同时使用中文符号和单位符号。 + +| **正例** | **反例** | +| -------- | -------- | +| km/h | km/小时 | + +【规则】词头不得孤立使用。 + +| **正例** | **反例** | +| -------- | -------- | +| 64Kbit/s | 64K | + +【规则】常用单位符号请参考下表。 + +| 单位名称 | 符号 | +| -------- | -------- | +| [小]时 | h | +| 分 | min | +| 秒 | s | +| 毫秒 | ms | +| 比特 | bit | +| 千比特 | kbit （表示1000概念时，使用小写k；表示1024概念时，使用大写K） | +| 兆比特 | Mbit | +| 字节 | Byte | +| 千字节 | kB（表示1000概念时，使用小写k；表示1024概念时，使用大写K） | +| 兆字节 | MB | +| 吉字节 | GB | +| 比特/秒 | bit/s （bit/s和bps都正确，但前者更正式） | +| 字节/秒 | Byte/s | +| 千米 | km | +| 米 | m | +| 厘米 | cm | +| 毫米 | mm | +| 微米 | μm | +| 分贝 | dB | +| 摄氏度 | ℃ | +| 华氏度 | ℉ | +| 开[尔文] | K | +| 赫[兹] | Hz | +| 帕[斯卡] | Pa | +| 千克（公斤） | kg | +| 克 | g | + + +## 标点符号 + + 【规则】逗号：不可滥用，不可“一逗到底”。 +| **正例** | **反例** | +| -------- | -------- | +| 帐务计费中心主要负责话单处理和帐务处理。帐务计费中心同计费网关之间有一个话单接口，用于帐务计费中心取用户话单。话单文件采用“\*.txt”的形式。 | 帐务计费中心主要负责话单处理和帐务处理，帐务计费中心同计费网关之间有一个话单接口，用于帐务计费中心取用户话单，话单文件采用“\*.txt”的形式。 | + +【规则】句号： + +- 在正文描述下紧接图或表时，句子说明已完整，以句号结束。 + | **正例** | **反例** | + | -------- | -------- | + | 具体参数说明如表1-2所示。 | 具体参数说明如表1-2所示： | + +- 当一个句子包含在另一个句子中，并且前者属于后者的一部分时，前者句末不加句号。 + | **正例** | **反例** | + | -------- | -------- | + | 在使用xxx（以下简称为x）之前，请先仔细阅读本手册的内容。 | 在使用xxx（以下简称为x。）之前，请先仔细阅读本手册的内容。 | + +- 括号中的内容不属于前一个句子，而是作为一个独立句子并且需要带括号时，句尾加句号。 + +【规则】冒号：不能在一个句子中连续使用冒号，避免导致冒号所提示的范围模糊。 + +| **正例** | **反例** | +| -------- | -------- | +| 正例1：
计费策略：A1 表示计费，A2 表示不计费。
正例2：
计费策略：
- A1：计费
- A2：不计费 | 计费策略：表示计费：A1，表示不计费：A2。 | + +【规则】圆括号： + +- 中文文档中默认使用全角括号（代码块等特殊位置除外）。 + +- 不要在括号中出现太长的说明文字。如果有较长的说明信息，建议作为一个单独的“[说明](#提示与说明)”。 + +【规则】句号、问号、叹号、逗号、顿号、分号和冒号不出现在一行之首。 + +【规则】引号、括号、书名号的前一半不出现在一行之末，后一半不出现在一行之首。 + +【规则】破折号和省略号都占两个字的位置，中间不能断开。 + +【规则】引号：中文文档中默认使用全角引号（代码块等特殊位置除外）。 + +【建议】问号：界面提示、CLI操作提示、语音提示、FAQ中可以使用问号。其他场景限制使用问号。 + +【建议】感叹号：任何场景下，不建议使用感叹号。 + +【建议】省略号：为使文档中描述的信息准确、全面，应尽量少用省略号或“等”。 + +【建议】其他：谨慎使用“√”“×”，在不同国家对这两个符号的理解可能正好相反。 + + +## 字符转义 + +【规则】要显示原本用于格式化Markdown文档的字符，请在字符前添加反斜杠\进行转义，确保显示正常。 + +常见的可用于转义的字符有：“\”、“、”、“\*”、“_”、“{}”、“[]”、“（）”、“\#”、“+”、“-”、“.”、“！”、“|”等。 + +| 正例 | 反例 | +| -------- | -------- | +| \\* 文本内容 | \* 文本内容 | + +【规则】对于特殊字符需使用特定的转义符号： + +- “<”使用“&lt”转义。 + +- “>”使用“&gt”转义。 + +- “&”使用“&amp”转义。 + + +## 文件路径 + +文件路径指文件在计算机上的位置。 + +【规则】涉及电脑分区的文件，文件路径需包含明确的根目录。 + +【建议】文件路径尽量使用斜杠“/”来作为文件夹之间的分隔符。 + +【建议】尽量避免文件路径过长的情况。 + + +## 代码与注释 + + +### 行内代码 + +【规则】对于正文描述中涉及代码的内容，比如实际代码中的方法名、参数名或代码文件名等，使用`包裹显示。 + +| 正例 | 反例 | +| -------- | -------- | +| 在`index.js`文件中实现页面跳转。 | 在index.js文件中实现页面跳转。 | + + +### 代码块 + +【规则】对代码示例、命令行使用代码样式。在Markdown中，使用```呈现代码样式，同时指定语言类型。 + +![代码块示例](figures/code-block-example.png) + +【规则】代码块内容应符合对应语言的通用编程规范。 + +【规则】完整举例中的代码块复制后可直接执行，且执行结果与文档描述一致。 + +【规则】如果代码块中没有标识行号，则不添加行号标识。 + +【规则】代码块显示符合缩进要求。 + +【建议】代码块中的关键代码段提供注释说明。 + + +### 注释 + +【规则】适时为代码块添加注释，特别是有解释说明、开发建议或注意事项的位置。恰当的注释可有效提升代码块可读性，帮助开发者快速掌握开发过程。 + +【规则】注释符与代码块语法保持一致，禁止自创注释符。注释符与注释内容间统一添加一个空格。例如：对于JavaScript代码块，注释写法为“// 注释内容”。 + +【规则】当一行注释内容过长时，注意断句切分到下一行呈现。 + + +## IP及MAC地址 + +【规则】IP地址举例只能使用私网IP，禁止使用公网IP（严禁使用实际现网数据）。私网IP地址范围如下。 + +| 组网种类 | 地址范围 | +| -------- | -------- | +| A | 10.0.0.0～10.255.255.255 | +| B | 172.16.0.0～172.31.255.255 | +| C | 192.168.0.0～192.168.255.255 | + +【规则】表示具体组网和路由信息时，IP地址和掩码必须同时出现。 + +- 图片和表格中可以使用如“x.x.x.x/24”的方式，“24”表示掩码长度。 + +- 正文中必须使用255.255.255.0格式表示掩码，如“IP地址为10.10.10.1，子网掩码为255.255.255.252”。 + +【规则】涉及域名示例时，使用开源网址：www.example.com。 + +【规则】涉及MAC地址示例时，在保持格式正确的情况下，使用“X”进行模糊处理。 + +| 正例 | 反例 | +| -------- | -------- | +| 00-01-XX-XX-XX-XX
00:01:XX:XX:XX:XX | 无 | + + +## 个人信息 + +【规则】严禁使用真实的个人信息。 + +【规则】涉及个人电话号码示例时，在保持格式正确的情况下，使用“\*”进行模糊处理。 + +【规则】国际电话号码前添加国家码和地区码，并分别用括号括起，如(86) (755) \*\*\*\*\*\*\*\* [Shenzhen, China]。 + +【规则】涉及个人身份证号、帐号名示例时，在保证格式正确的情况下，使用“\*”进行模糊处理。 + +【规则】涉及邮箱示例时，在保证格式正确的情况下，进行模糊处理，例如：\*\*\*@example.com。 + +【建议】涉及个人姓名示例时，尽可能使用通用名。 + diff --git a/zh-cn/contribute/style-guide/style-guide-document-structure.md b/zh-cn/contribute/style-guide/style-guide-document-structure.md new file mode 100644 index 0000000000000000000000000000000000000000..62a3237c75c1cf0c84ee05dc7b7aea890f8d4746 --- /dev/null +++ b/zh-cn/contribute/style-guide/style-guide-document-structure.md @@ -0,0 +1,140 @@ +# 文档结构 + + +## 标题 + + +### 标题规则 + +【规则】标题应概括反映章节的中心内容，体现章节内容的核心关键词。避免使用“概述Overview”、“简介Introduction”等不带有核心关键词的标题，应补充核心关键词如“内核概述”、“OpenHarmony简介”。 + +【规则】相同级别、相同类型的标题结构保持一致。 + +| **正例** | **反例** | +| -------- | -------- | +| 内核概述
驱动概述
【点评】同为概念类页面，标题风格保持一致。 | 内核介绍
驱动概述 | +| 音频播放开发指导
音频管理开发指导
【点评】同为操作/指导类页面，标题风格保持一致。 | 音频播放开发指导
音频管理开发 | + +【规则】标题中使用的缩略语不必给出全称。标题中出现某一缩略语时，采用以下方式处理： + +- 首次出现该缩略语时，需在随后的正文中给出其全称。 + +- 非首次出现该缩略语时，不需在随后的正文中给出其全称。 + +- 无法判断是否为首次出现该缩略语时，按首次出现该缩略语处理。 + +【规则】标题中不能出现特殊字符。 + +- 这些特殊字符包括：+、-、\*、?、|、^、~、""、'、\、/。由于这些特殊字符带有某些特殊的语义，当这些特殊字符在标题中出现时，会导致标题无法正确显示或无法出现在搜索结果中。 + +- 当标题中无法避免产品名称、功能或特性连用时，请谨慎使用半角的“/”或“&”。 + +【规则】标题结尾不允许使用句号、问号、冒号等标点符号。即使是FAQ的标题也不例外。 + +【规则】标题中不能带上下标。 + +【规则】标题中存在补充说明文字时，统一使用圆括号标识。补充说明文字区分不同维度时，用中文逗号分隔。如：快速入门（标准系统，安装包方式）。 + +【建议】中文标题长度不超过15个汉字，英文不超过25个字符（包括空格）。 + +【建议】概念类/描述类/功能介绍类章节的标题采用名词或名词性词组。 + +| **正例** | **反例** | +| -------- | -------- | +| OpenHarmony介绍 | 介绍OpenHarmony | + +【建议】任务类章节的标题建议采用动宾结构。 + +| 建议 | 不建议 | +| -------- | -------- | +| 开发首个Hello World | 首个Hello World开发 | + + +### 标题样式 + +【规则】标题包含一级标题、二级标题、三级标题、四级标题……，同一页面内标题层级建议不超过四级。 + +【规则】标题级别必须遵守一级标题 > 二级标题 > 三级标题 > 四级标题的顺序。 + +【规则】不能混用标题的级别，例如：一级标题下面不能直接使用三级标题、四级标题；二级标题下面不能直接使用四级标题。 + + **图1** Markdown中标题编辑样式 +![Markdown中标题编辑样式](figures/heading-edit-style.png) + + **图2** Markdown中标题预览样式 +![Markdown中标题预览样式](figures/heading-preview-style.png) + +## 段落 + +【规则】一个段落只能有一个主题句或中心句。主题句或中心句置于段首。 + +【规则】段落之间要有[清晰的逻辑结构](style-guide-language-style.md#清晰)。 + +【规则】根据内容特点，段落句子使用陈述、肯定或祈使语气，避免使用感叹语气。 + +【建议】一个段落的长度≤7行，最佳段落长度≤4行。 + +【建议】对于技术描述类主题，“字不如表、表不如图”，推荐使用文字、图、表相结合的方式，使内容更易理解。 + +【建议】不出现连续3个以上的纯文字段落。通过图、表等方式避免文字描述的单一性。 + +【建议】段落内容使用正文样式，不要加粗。 + + +## 句子 + +【规则】每个句子只有一个主题。 + +【规则】使用直接陈述，避免双重否定和反问句。 + +【规则】避免“名词 + 名词 + 名词”修饰方式。 + +| **正例** | **反例** | +| -------- | -------- | +| 无 | 配置管理模块
【点评】该短句可能存在如下断句：配置“管理模块”，或“配置管理”模块，根据实际语义优化描述。 | + +【规则】句子的主语应该明确。省略主语时，要保证用户能迅速并正确地确定主语。同一个句子内，避免主语变化。 + +| **正例** | **反例** | +| -------- | -------- | +| 无 | 提示出错
【点评】缺少主语，如工具提示出错、编译子系统提示出错，在描述时尽量具体、明确。 | + +【规则】使用主谓结构、主谓宾结构的简单句，而非复合句。把复合句改为列表或分拆成简单句和简单复合句。 + +【规则】避免使用长连句，同一个句子中的逗号个数应小于9。 + +【建议】用祈使句表示动作。 + +| 建议 | 不建议 | +| -------- | -------- | +| 在弹出的对话框中，单击“确定”按钮。 | 在弹出的对话框中，请您单击“确定”按钮。 | + +【建议】中文句子长度不超过50个汉字，英文句子长度不超过30个字符。 + +【建议】句子样式默认采用正文样式，不要加粗或添加背景色。 + + +## 目录 + +文档目录分为手册级目录、页面内目录，便于用户高效浏览、获取关键内容。 + +【规则】手册级目录：手册级目录定义以Docs仓库内最小文件夹级别管理。在文件夹内新增页面、修改页面名称、删除页面时，都需同步更新手册级目录。 + +【规则】页面内目录：页面内目录由页面内标题自动生成，写作时请遵循页面内[标题规范及样式](#标题)。 + + +## 文件夹及文件命名 + +【规则】文件夹名：使用文档描述对象的主题英文名称，如ability、ui等，全小写。 + +【规则】Markdown文件命名规范： + +- 由字母、数字、中划线“-”组成。统一使用“.md”（小写）后缀。 + +- 除Readme.md外，其他文件名原则上全小写。 + +- 语义化，文件名能对文档主题内容进行概括，建议取自该文档的英文标题，如：ability-assistant-guidelines.md。 + +- 原则上不超过4个英文单词。 + +- 同一文件夹下，文件名不允许重复。 diff --git a/zh-cn/contribute/style-guide/style-guide-language-style.md b/zh-cn/contribute/style-guide/style-guide-language-style.md new file mode 100644 index 0000000000000000000000000000000000000000..79fb85b067645c6e135b32c23970c2187fbfde68 --- /dev/null +++ b/zh-cn/contribute/style-guide/style-guide-language-style.md @@ -0,0 +1,197 @@ +# 语言风格 + + +## 人称及语态 + +【规则】使用第二人称。人称代词默认省略，必须出现时，推荐使用“开发者”而不是“你”。 + +| **正例** | **反例** | +| -------- | -------- | +| 使用IDE创建卡片工程。 | 我们使用IDE创建卡片工程。 | + +【建议】尽量使用主动语态。即句子主语是执行动作的人或事物，而不是被操作的事物。 + +| 建议 | 不建议 | +| -------- | -------- | +| 配置参数A，声明支持B功能。 | A参数被配置后，即可支持B功能。 | + + +## 语气及用词 + +【规则】客观陈述内容，口吻友好。 + +| **正例** | **反例** | +| -------- | -------- | +| 确保配置正确。否则，会导致系统工作不正常。 | 你必须保证配置正确。否则后果自负。 | + +【规则】避免使用口语化词语。 + +| **正例** | **反例** | +| -------- | -------- | +| 无 | “不准”、“……的话”、“就可以了”、“做……用”等。 | + +【规则】避免行话。行话只有小部分人员能理解，且难以翻译。 + +| **正例** | **反例** | +| -------- | -------- | +| 非法访问内存空间 | 踩内存 | + +【规则】避免成语和俗语。成语和俗语翻译时很难有效传达其确切含义，没有必要在技术资料中存在。 + +【规则】避免使用可能带有偏见或歧视含义的词汇，包括性别、种族、文化、年龄、技能、职业、宗教、经济水平等方面的偏见或歧视。 + +【规则】避免使用可能会引起操作者负面情绪的词语。 + +| **正例** | **反例** | +| -------- | -------- | +| 无 | “你已被踢出” | + + +## 用户视角 + +【规则】为目标用户（指目标读者，本文简称用户）写作： + +- 明确文档面向的用户（如产品经理、开发者），从而明确用户关注的内容要点，提供且仅提供用户关注的内容。写作中，时刻站在用户视角，思考文章是否覆盖了内容要点、有无冗余。 + +- 针对不同技能水平（如新手、资深）的用户提供支撑信息。 + +- 按照用户认知习惯呈现信息（请参考“[清晰](#清晰)”）。 + +【规则】面向用户场景和用户任务写作： + +- 文档内容应面向用户的真实场景和目标/任务，而非产品功能。 + +- 标题明确体现任务目标。 + +- 对于复杂任务流（超过5步），在操作开始前提供操作流程图或表。 + +- 提供清晰的、step-by-step的操作指导。适当配合界面截图使操作更直观，仅截取关键信息。 + +- 为用户任务就近提供操作支撑信息。 + +- 提供任务全流程所需的支撑信息，例如必要的背景信息、前提条件、准备动作、操作成功的验证方法、常见的故障处理和错误预防信息。 + +- 为所呈现的信息提供必要的理由（例如对用户理解或完成开发任务没有帮助的内部实现原理不需要提供）。 + + +## 完整 + +【规则】避免任务场景缺失。开始写作前，应通过用户与任务分析活动，明确文档要提供哪些任务场景的指导信息。 + +【规则】通过写作模板来保证内容的完整性： + +- OpenHarmony文档遵从结构化、模块化理念，对于每类信息，均根据用户的信息需求提供相应内容模板，即“[OpenHarmony文档写作模板](https://gitee.com/openharmony/docs/tree/master/zh-cn/contribute/template)”。请从中选择最贴近待写作内容的模板，保证知识点覆盖完整。 + +- 写作模板中“必选”的节点，禁止删除。 + +- 写作模板中“可选”的节点，在确定不涉及的情况下，删除即可。 + + +## 具体 + +【规则】用具体的描述代替抽象/晦涩的描述。 + +| **正例** | 反例 | +| -------- | -------- | +| 在编译构建过程中，提示LABEL_VALUE_ERROR错误信息。 | 编译构建失败。 | + +【规则】表示数量或程度时，避免用笼统的“多”“少”“大”，改为具体的、易于感知或衡量的数字。 + +| **正例** | 反例 | +| -------- | -------- | +| 文件大于16MB | 文件超限 | +| 等待30分钟左右 | 等待较长的时间 | +| CPU运行速度提升80% | 性能增强 | + + +## 简洁 + +【规则】使用主谓结构、主谓宾结构的句子，避免添加不必要的修饰成分。 + +【规则】避免使用长连句。同一句子中的逗号数不能超过5个。 + +【规则】禁止使用双重否定。 + +【规则】言简意赅，直接陈述观点。避免无意义的词语，包括表示程度、语气的词。 + +| **正例** | 反例 | +| -------- | -------- | +| 属性不允许重复定义。 | 每个属性最多只允许出现一次。 | +| 绑定服务与通知。 | 将服务与通知绑定就好了。 | + +【规则】根据用户的技能水平，剔除不必要的信息。 + + +## 清晰 + +【规则】确保语言描述清晰，不模糊，不晦涩，易理解（传递一个清楚的意思）： + +- 遵循“[具体](#具体)”、“[简洁](#简洁)”的要求。 + +- 确保每个代词都有清晰的指代，能够通过上下文清晰获取其指代对象，便于理解与翻译。 + +- 参数取值原则、原理描述清晰易懂。 + | **正例** | 反例 | + | -------- | -------- | + | 当参数A设置为1时：
- 如果参数B设置为1，表示有下一级跳转，此时页签为方形9宫格。
- 如果参数B设置为0，表示无下一级跳转，此时页签自动变为圆形9宫格。 | 在参数A为1同时参数B为1，如有下一级跳转则页签为方形9宫格，若无下一级跳转则界面页签会自动变为圆形9宫格。 | + +- 避免使用引起歧义的词。 + | **正例** | **反例** | + | -------- | -------- | + | 接通开发板电源。 | 按下开发板电源开关。 | + +- 避免使用含义模糊的词，如表示程度、强调等语气的词。 + | **正例** | **反例** | + | -------- | -------- | + | 无 | - 表示程度的词：较多（more）、较好（better）、基本地（basically）、决定性的（decisively）、最后的  ( finally )、很（very）、可能（may/maybe/could）、大概（probably）、通常( usually )、一般  ( generally )。
- 表示转折的词：当然（of  course）、然而（however）。
- 表示量的词：有些（some）、非常（very）、大量（large  number）、一些（several）、少许（few）。 | + +【规则】确保逻辑清晰： + +- 采用合理的逻辑结构（写作顺序），使章节/段落/步骤/句子顺序符合用户认知习惯。以下常用写作顺序可以独立使用，也可配合使用。 + | **逻辑结构（写作顺序）** | 特征 | 适用的典型信息类型（不限于） | + | -------- | -------- | -------- | + | 先总后分 | 先综述总论点（如特性概述、开发流程概述），再依次展开分论点（子特性详细介绍、开发任务流详细介绍）。
总论点下的分论点做到完全穷尽（不遗漏）、相互独立（无交叠）。 | 功能/场景描述类
开发指导类 | + | 按时间顺序 | 时间、流程或因果上的有先有后。 | 开发指导类 | + | 按空间/结构顺序 | 从上层到下层；从整体到局部。 | 架构描述类
组网描述类 | + | 按重要性顺序 | 从重要到次要；从基础到特殊。 | 开发指导类
问题分析类 | + | 按"情境-冲突-问题-回答"顺序 | 通过追溯问题的起源和发展，引入用户熟悉的情境，然后说明冲突，从而提出最初的问题，最后给出解决方案（也就是即将阐述的主题）。 | 功能/场景描述类 | + +- 对于开发指导类内容，能让用户直观了解具体场景/任务的完整开发流程。 + +- 对于存在分支的步骤，提供明确的选取原则。 + +- 适当使用图、表，使逻辑和表意更直观。 + + +## 一致 + +【规则】用词一致：术语、缩略语、描述同一对象的词汇要全文一致，符合用户的心理预期，禁止使用不同的词汇（包括中英文混用）描述同一事物或操作。 + +OpenHarmony常用词必须遵从下表。 + +| 正例 | 反例 | +| -------- | -------- | +| 登录 | 登陆 | +| 单击 | 点击 | +| 帐户 | 账户 | +| 帐号 | 账号 | +| 图像 | 图象 | +| 计费 | 记费 | +| 阈值 | 阀值 | +| 重写 | 复写 | +| 命令 | 指令 | +| 外形 | 外型 | + +【规则】结构一致：相同文档或者同类信息，保持结构一致，有助于用户对文档结构的把握，方便信息的查找和理解。请优先在“[OpenHarmony文档写作模板](https://gitee.com/openharmony/docs/tree/master/zh-cn/contribute/template)”中选择最贴近待写作内容的模板，遵循模板要求写作。 + +【规则】句式一致：使用一致的句式，不但使技术文档对外表现出一致的风格，也有助于用户在理解内容时，符合已经形成的思维惯性，理解起来更简单。例如统一使用祈使句描述动作。 + +【规则】格式一致：同类元素如[代码块](style-guide-content-elements.md#代码与注释)、[文件路径](style-guide-content-elements.md#文件路径)等，格式保持一致，便于用户理解。 + +【建议】下表给出了另一部分常用词的推荐用法，请参考。 + +| 建议 | 不建议 | +| -------- | -------- | +| 界面 | 页面 | +| 短消息 | 短信 | +| 数据包 | 数据报 | diff --git a/zh-cn/contribute/style-guide/style-guide-overview.md b/zh-cn/contribute/style-guide/style-guide-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..c411b8bf9dedeef16697b12b8260b00e4bc9affc --- /dev/null +++ b/zh-cn/contribute/style-guide/style-guide-overview.md @@ -0,0 +1,21 @@ +# 关于本指南 + + +本指南针对OpenHarmony文档的语言风格、文档结构、内容元素等提供规范要求或参考建议，确保OpenHarmony文档具备一致的风格，同时帮助开发者高效参与文档贡献。 + + +在开始OpenHarmony文档写作前，请先浏览本指南内容，参照相应要求或建议进行写作。 + + +此外，请优先在“[OpenHarmony文档写作模板](https://gitee.com/openharmony/docs/tree/master/zh-cn/contribute/template)”中选择最贴近待写作内容的模板，遵循模板要求进行写作。写作模板提供特定类型文档的针对性写作指引，充分利用写作模板将事半功倍。 + + +本指南持续更新，欢迎提出改进意见。 + + +> **说明：** +> 本指南的内容分为【规则】、【建议】两类： +> +> - 【规则】表示规范要求，必须遵从。 +> +> - 【建议】表示参考建议，可选遵从。