• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Writing Instructions
2
3This document describes the writing specifications for contributing OpenHarmony documents.
4
5## Naming Specifications
6
7To submit a new document, create a new  **.md**  file in the  **doc**  directory of the project code on Gitee. The file name must be in the  _xxx-xxx_**.md**  format.
8
9For example, a document that describes writing specifications can be named  **write-standard.md**.
10
11## Content Specifications
12
13The content should be concise and intuitive. Introductory documents describe principles, architecture, and design ideas in a concise manner, and operation documents describe key steps to help other developers. Chinese is preferred. It is recommended that both Chinese and English be supported. The OpenHarmony will be updated continuously to ensure the synchronization between Chinese and English.
14
15**Title**
16
17It is recommended that the title have no more than three levels.
18
19Use the verb-object structure in operation documents if possible, and the execution subject should be clearly described. \(e.g., Apply for Privilege\)
20
21**Body**
22
23The following shows the structure of an  **operation document**  for porting.
24
25-   Purpose \(Briefly describe the purpose of the operation, for example, the model of the board to which the port is to be migrated.\)
26
27-   Hardware and software requirements
28
29-   Detailed steps
30
31-   Result verification
32
33    Writing requirements:
34
35    -   The APIs used in steps must be described in the available capabilities at the beginning of the document.
36    -   If an operation is optional, specify the optional conditions.
37    -   If API calls are required in a step, provide the API, its description, and sample code if any.
38
39
40**Introductory documents**: The development guide of a feature is used as an example to show the document structure.
41
42-   Overview \(concepts and principles\)
43
44-   Functions \(supported APIs\)
45
46-   Development process \(steps of how to use and develop\)
47
48-   Programming examples \(sample code\)
49
50-   Important notes
51
52
53**Pictures**
54
55Pictures are stored in the **images**  folder in the directory where the document is stored. For example,
56
57Pictures used in  **OpenHarmony\_DOCUMENTS/docs/quick-start/writing-instructions.md**  are stored in the following directory:
58
59**OpenHarmony\_DOCUMENTS/docs/quick-start/images**
60
61Use relative paths to reference pictures in the document.
62
63> **CAUTION**
64> Use the original pictures to avoid intellectual property infringement risks.
65
66-   Pictures are clear and complete. For example, a flowchart has a start and an end.
67-   The graphics has clear logic and are provided with text descriptions. Do not separate the graphics from the text.
68-   It is recommended that the image height be about 640 px, the image width be less than or equal to 820 px, the image format be .png, and the image size be less than or equal to 150 KB.
69-   The text on pictures should be Chinese in Chinese documents and English in English documents.
70-   It is recommended that pictures be named based on the content. Using only a number is difficult for picture inheritance.
71
72> **NOTE**
73> Reference:
74> !\[\]\(./pic/pic-standard.png\)
75
76If a self-made picture is used, refer to the following figure to configure the color. The format can be  **png**,  **jpg**,  **gif**, and so on.
77
78**Figure  1**  Color example
79
80![](figures/color.png "color example")
81
82For screenshots, see the requirements below. If you need to highlight key information in the figure, add a red box or text remarks.
83
84Stroke width: 0.75 pt
85
86Line color: CE0E2D
87
88Chinese font: MicrosoftYaHei
89
90English font: Arial
91
92Font size: 10 pt
93
94**Table**
95
96You can insert a table in  **.md**  documents in the following format:
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**Table  1**  Parameters
111
112| Tables |    Type     | Note |
113| ------ | :---------: | ---: |
114| first  |  standard   | None |
115| second | outstanding |    5 |
116| third  |   inside    | with |
117
118**Code**
119
120The code example shows how to implement a specific feature. Developers can use the code example to write and debug code. The code requirements are as follows:
121
122-   The logic and syntax of the code are correct.
123-   Describe the return values if any.
124-   Ensure that key fields are highlighted in bold and that comments are provided for key steps.
125
126