1# 写作规范<a name="ZH-CN_TOPIC_0000001053707964"></a> 2 3本文介绍OpenHarmony文档贡献的写作规范。 4 5## 命名规范<a name="section6823246189"></a> 6 7如需提交新的文档，在Gitee上工程代码doc目录下创建新的.md文件，命名需遵循xxx-xxx.md格式，根据文档的内容来声明。 8 9比如介绍写作规范的文档，可以命名为write-standard.md。 10 11## 内容规范<a name="section650663210183"></a> 12 13以简洁、直观地表达所述内容为目的，介绍性文档言简意赅介绍原理、架构、设计思路等，操作类文档写明关键步骤，以便能对其他开发者起到帮助。可以优先使用中文，建议中英文都支持，OpenHarmony也将持续更新，保证中英文的同步。 14 15**标题** 16 17建议标题层级不超过三级。 18 19操作类文档标题尽量用动宾结构，执行的主体要描述清楚。（例如：申请权限） 20 21**正文** 22 23**操作类文档**以移植为例，文档结构可以参考如下： 24 25- 目的（简述操作目的，如移植到哪款型号的单板） 26 27- 软硬件环境准备 28 29- 移植具体步骤 30 31- 结果验证 32 33 步骤写作要求： 34 35 - 步骤里涉及的接口在前面开放能力介绍里有说明。 36 - 如果操作可选，要明确可选条件 37 - 每一个开发步骤，如果涉及接口调用，需要清晰给出使用的接口及其使用说明，或给出示例代码 38 39 40**介绍性文档**以开发指南某一功能为例，文档结构可以参考如下： 41 42- 概述（概念及原理介绍） 43 44- 功能（支持的接口列表） 45 46- 开发流程（如何使用及相应步骤） 47 48- 编程实例（提供具体代码示例） 49 50- 注意事项 51 52 53**图片** 54 55图片统一存放到文档同级目录下的pic文件夹中（英文文档对应pic-en），如： 56 57“OpenHarmony\_DOCUMENTS/docs/quick-start/write-standard.md”中使用的图片，统一放置到 58 59“OpenHarmony\_DOCUMENTS/docs/quick-start/pic”目录下，文档中使用相对路径引用图片。 60 61> **注意：** 62>请使用原创图片，避免存在知识产权侵权风险。 63 64- 图形清晰可辨识，图形信息完整，如流程图有“开始”和“结束”。 65- 图形逻辑清晰，图文配合使用，切忌图文分离。 66- 图片高度建议在640px左右、宽度不超过820px、图片一般为.png格式，大小不超过150K。 67- 中文用中文图，英文用英文图形。 68- 图片建议根据内容命名，只用数字序列不利于后续图片的继承。 69 70> **说明：** 71>引用方式： 72>!\[\]\(./pic/pic-standard.png\) 73 74如果是自制图片，配色请参考如下，格式不限png/jpg/gif...均可。 75 76**图 1** 配色示例<a name="fig952595173513"></a> 77 78 79如果是截图请参考如下，如需突出图形中的关键信息，可增加红色框线或者文字备注说明。 80 81线条宽度：0.75pt 82 83线条颜色：CE0E2D 84 85中文字体：微软雅黑 86 87英文字体：首选Arial 88 89字体大小：10pt 90 91**图 2** 截图示例<a name="fig1472123913217"></a> 92 93 94**表格** 95 96在md中可以按照如下形式插入表格。 97 98Input 99 100``` 101| Tables | Type | Note | 102| ----------- |:-------------:| -----:| 103| first | standard | None | 104| second | outstanding | 5 | 105| third | inside | with | 106``` 107 108Output 109 110**表 1** 参数表 111 112<a name="table163931041183019"></a> 113<table><thead align="left"><tr id="row1393134183014"><th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.1"><p id="p1539314418307"><a name="p1539314418307"></a><a name="p1539314418307"></a>Tables</p> 114</th> 115<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.2"><p id="p1339324120303"><a name="p1339324120303"></a><a name="p1339324120303"></a>Type</p> 116</th> 117<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.3"><p id="p13932041133012"><a name="p13932041133012"></a><a name="p13932041133012"></a>Note</p> 118</th> 119</tr> 120</thead> 121<tbody><tr id="row1839304110309"><td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.1 "><p id="p4393174143014"><a name="p4393174143014"></a><a name="p4393174143014"></a>first</p> 122</td> 123<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.2 "><p id="p6393141133013"><a name="p6393141133013"></a><a name="p6393141133013"></a>standard</p> 124</td> 125<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p17393184112307"><a name="p17393184112307"></a><a name="p17393184112307"></a>None</p> 126</td> 127</tr> 128<tr id="row1039318412306"><td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.1 "><p id="p113941541103012"><a name="p113941541103012"></a><a name="p113941541103012"></a>second</p> 129</td> 130<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.2 "><p id="p83941841153016"><a name="p83941841153016"></a><a name="p83941841153016"></a>outstanding</p> 131</td> 132<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p1539404114305"><a name="p1539404114305"></a><a name="p1539404114305"></a>5</p> 133</td> 134</tr> 135<tr id="row6547101813118"><td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.1 "><p id="p35483184313"><a name="p35483184313"></a><a name="p35483184313"></a>third</p> 136</td> 137<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.2 "><p id="p1554821817318"><a name="p1554821817318"></a><a name="p1554821817318"></a>inside</p> 138</td> 139<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p15548201819310"><a name="p15548201819310"></a><a name="p15548201819310"></a>with</p> 140</td> 141</tr> 142</tbody> 143</table> 144 145**代码** 146 147代码示例说明了如何实现特定功能，开发人员使用代码示例来编写和调试代码。代码要求如下： 148 149- 代码的逻辑和语法正确 150- 如果有返回值，也一并描述 151- 保证代码中关键段用粗体突出显示，关键步骤要有注释说明 152 153
