OpenHarmony系统文档贡献的写作规范

一、前言
二、命名规范
三、内容规范
- 1.标题
- 2.正文
- 3.图片
- 4.表格
- 5.代码
四、总结

一、前言

已经有一段时间的连续写作了，这次我们来谈谈在OpenHarmony上贡献自己的文档的规范，同时也是一种平时写作的可以参考的规范，话不多说，开始了~~

二、命名规范

如需提交新的文档，在Gitee上工程代码doc目录下创建新的.md文件，命名需遵循xxx-xxx.md格式，根据文档的内容来声明。

比如介绍写作规范的文档，可以命名为write-standard.md

这个命名规范比较简单，一般来讲达意即可，下面的内容规范才是今天的重点

三、内容规范

1.标题

标题最好不要超过三级，标题层级太多可能导致内容在手机网页显示不佳，例如目前的微信文章就不支持4级标题，然后标题简单明了即可

2.正文

操作类文档以移植为例，文档结构可以参考如下：

目的（简述操作目的，如移植到哪款型号的单板）
软硬件环境准备
移植具体步骤
结果验证

步骤写作要求：
- 步骤里涉及的接口在前面开放能力介绍里有说明。
- 如果操作可选，要明确可选条件
- 每一个开发步骤，如果涉及接口调用，需要清晰给出使用的接口及其使用说明，或给出示例代码

这部分内容每个部分都各不相同，总体还是分成理论，步骤，实践，其他类似都是一样的，这部分基本上等于自由发挥

3.图片

首先最重要的一点就是图片需要原创，避免知识产权纠纷

图片统一存放到文档同级目录下的pic文件夹中（英文文档对应pic-en），如：

“OpenHarmony_DOCUMENTS/docs/quick-start/write-standard.md“中使用的图片，统一放置到

“OpenHarmony_DOCUMENTS/docs/quick-start/pic“目录下，文档中使用相对路径引用图片。

图形清晰可辨识，图形信息完整，如流程图有“开始”和“结束”。
图形逻辑清晰，图文配合使用，切忌图文分离。
图片高度建议在640px左右、宽度不超过820px、图片一般为.png格式，大小不超过150K。
中文用中文图，英文用英文图形。
图片建议根据内容命名，只用数字序列不利于后续图片的继承。
如果是自制图片，配色请参考如下，格式不限png/jpg/gif…均可。
如果是截图请参考如下，如需突出图形中的关键信息，可增加红色框线或者文字备注说明。
图片的命名最好也是使用内容进行命名，不要使用数字序列进行命名

如果需要添加文字注释，最好循序以下格式

线条宽度：0.75pt
线条颜色：CE0E2D
中文字体：微软雅黑
英文字体：首选Arial
字体大小：10pt

4.表格

在md中可以按照如下形式插入表格。

| Tables      | Type          | Note  |
| ----------- |:-------------:| -----:|
| first       | standard      |  None |
| second      | outstanding   |     5 |
| third       | inside        |  with |

上面那部分代码直接复制到md代码中即可

5.代码

代码示例说明了如何实现特定功能，开发人员使用代码示例来编写和调试代码。代码要求如下：

代码的逻辑和语法正确
如果有返回值，也一并描述
保证代码中关键段用粗体突出显示，关键步骤要有注释说明

这部分代码以简单明了为主，但基本的代码规范也是需要遵循的，具体的代码规范可以参考官方文档代码规范

四、总结

这是官方推荐的文档规范，养成习惯对于后面的开发会有非常大的帮助，这里给大家举一个反面例子QQ互联文档,并非有意吐槽，而是文档真的写的太烂了，我们下一篇见~~