1# Development Guide Writing Template
2
3### Change History
4| Change Description                                                                | Date        |
5| ----------------------------------------------------------------------- | ------------ |
6| The development guide is provided by kit, and therefore this template is updated accordingly.|  March 2024 |
7
8
9
10> **NOTE**
11>
12> _1. This template provides the recommended development guide document framework and writing instructions for typical knowledge points. In your writing, complete the development task scenario analysis and development guide outline design based on the specific **kit/solution/feature/function/module**, and then write the content based on this template._
13>
14> _2. Do not add any content between level-1 title (marked with #) and level-2 title (marked with ##)._
15>
16> _3. Delete all the writing instructions in italics from your formal documents._
17
18
19**_[General Instructions for Writing the Development Guide]_**
20
21_**1. Target audience**: internal and external developers (including product managers). Guidelines for UX designers are usually carried by UX design specifications and are not covered in the development guide. If UX design specifications need to be mentioned in the development guide, use hyperlinks._
22
23_**2. Content positioning**: Introduce what the kit/solution/feature/function/module is, why it is required, and how to design, develop, and release related applications/devices. The development guide aims to help developers learn necessary knowledge and achieve specified task objectives in actual development activities._
24
25_**3. User-oriented**: Always provide developer-concerned, perceptible, and useful content from the perspective of developers._
26
27_**4. Task-oriented**: Focus on actual tasks of developers, and provide complete, correct guidance that is easy to follow._
28
29_**5. Reference purposes**: This template only provides the basic document framework. You can adjust the content based on the actual requirements._
30
31_**6. Content that is open only to system applications**: For content that is open only to system applications, topic-level isolation is recommended in terms of concepts, principles, and development scenarios. In other words, use an independent .md file to carry the content, and append "(for System Applications Only)" to the title._
32
33
34## Introduction to *Example* (Replace it with a specific kit/solution/feature/function/module name.)
35
36_Mandatory. At the very beginning, describe the basic information about what it is, why it is needed, and when to use it, helping developers have a preliminary understanding of the kit/solution/feature/function/module name._
37
38_**[Developers' Concerns]**_
39
40_What is the kit/solution/feature/function/module (definition)?  What problems can it solve or what benefits can it bring (purpose/customer benefits - why)?_
41
42_**[Key Writing Points]**_
43
44- _Provide easy-to-understand and scenario-specific descriptions. Refer to the SCQA method below to introduce the scenarios and characteristics of the kit/solution/feature/function/module._
45  - _S: situation. Introduce a familiar scenario._
46  - _C: complication. Describe the conflict between the situation and requirement._
47  - _Q: question. Ask a question. What can I do in such a case?_
48  - _A: answer. Describe the solution.
49
50- _Visualize abstract concepts. You can provide content from the perspective of consumers for better understanding, for example, scenario effect in UX._
51
52_**[Writing Requirements]**_
53
54- _Provide clear content. Avoid vague, obscure, and ambiguous expressions._
55
56- _Use only necessary terms, acronyms, abbreviations, and proper nouns, and provide explanations or links to the glossary._
57
58- _Use consistent terms, acronyms, abbreviations, and proper nouns throughout the document._
59
60***[Example]***
61
62Form Kit provides an effective way of presenting information on the UI – service widget. A service widget (also called widget) is a set of UI components that display important information or operations specific to an application. It provides users with direct access to a desired application service, without the need to open the application first. A widget is usually displayed as part of the UI of another application (which can only be a system application, such as the home screen) and provides basic interactive features such as opening a UI page or sending a message.
63
64### Available Capabilities
65
66_Optional. Introduce the key open capabilities of the kit/solution/feature/function/module to support developers in model selection._
67
68_**[Developers' Concerns]**_
69
70_What key open capabilities does the kit/solution/feature/function/module provide?  _
71
72_**[Key Writing Points]**_
73
74- _Describe key open capabilities. There is no need to list all of them._
75
76_**[Writing Requirements]**_
77
78- _Provide clear content. Avoid vague, obscure, and ambiguous expressions._
79
80- _Use only necessary terms, acronyms, abbreviations, and proper nouns, and provide explanations or links to the glossary._
81
82- _Use consistent terms, acronyms, abbreviations, and proper nouns throughout the document._
83
84***[Example]***
85
86- Audio encoding: Audio applications (such as audio calling and audio recording applications) can send uncompressed audio data to the audio encoder for encoding. The applications can set parameters such as the encoding format, bit rate, and sampling rate to obtain compressed audio files in desired formats.
87- Video encoding: Video applications (such as video calling and video recording applications) can send uncompressed video data to the video encoder for encoding. The applications can set parameters such as the encoding format, bit rate, and frame rate to obtain compressed video files in desired formats.
88
89### Features
90
91_Optional. Introduce the highlights and advantages of the kit/solution/feature/function/module compared with counterparts in the industry to support developers in model selection._
92
93_**[Developers' Concerns]**_
94
95_What are the advantages of this kit/solution/feature/function/module?  _
96
97_**[Key Writing Points]**_
98
99- _Provide attractive highlights and advantages, and avoid insubstantial advertising. If there is no obvious highlight, delete this section._
100
101_**[Writing Requirements]**_
102
103- _Provide clear content. Avoid vague, obscure, and ambiguous expressions._
104
105- _Use only necessary terms, acronyms, abbreviations, and proper nouns, and provide explanations or links to the glossary._
106
107- _Use consistent terms, acronyms, abbreviations, and proper nouns throughout the document._
108
109***[Example]***
110
111- Low-latency playback
112
113  Unified low-latency and non-low-latency audio playback APIs are provided to achieve the lowest audio output latency on various hardware devices. For example, low-latency APIs can be used to implement fast and smooth audio playback in scenarios such as gaming, prompt/alarm tones, and Karaoke.
114
115- Low-power playback
116
117  In long-duration audio playback scenarios such as music playing and audiobook listening, a differentiated audio buffer processing mechanism is used for the screen-off scene. This helps audio playback consume less power by reducing the CPU wake-up frequency.
118
119### Basic Concepts
120
121_Optional. Describe the basic concepts that are common to all task scenarios._
122
123_**[Developers' Concerns]**_
124
125_What are the unique concepts that I need to know when using the kit/solution/feature/function/module?_
126
127_**[Key Writing Points]**_
128
129- _Provide only the concepts that are mandatory in development tasks._
130
131- _Describe here concepts used in multiple chapters such as the operation mechanism, restrictions, and development process. If a concept is used only in a chapter, describe the concept in that chapter only._
132
133- _Do not describe common concepts in the industry. Use common terms in the industry instead of jargon._
134
135- _If there are logical relationships between concepts, you are advised to use figures to describe the relationships._
136
137_**[Writing Requirements]**_
138
139- _Provide clear content. Avoid vague, obscure, and ambiguous expressions._
140
141- _Use only necessary terms, acronyms, abbreviations, and proper nouns, and provide explanations or links to the glossary._
142
143- _Use consistent terms, acronyms, abbreviations, and proper nouns throughout the document._
144
145***[Example]***
146
147Before developing relational databases, you must understand the following basic concepts:
148
149- **RDB**
150
151  A type of database based on the relational model of data. The RDB stores data in rows and columns. An RDB is also called RDB store.
152
153- **Predicate**
154
155  Property or feature of a data entity, or the relationship between data entities. It is mainly used to define operation conditions.
156
157- **Result set**
158
159  A set of query results used to access the data. You can access the required data in a result set in flexible modes.
160
161
162### Working Principles
163
164_Optional. Describe the working principles that are common to all task scenarios._
165
166_**[Developers' Concerns]**_
167
168_How does the kit/solution/feature/function/module work? What are the API calling and triggering time of key steps? I want to understand its principles for better use and debugging._
169
170_**[Key Writing Points]**_
171
172- _If the principle is simple and can be understood from the content under "Basic Concepts", do not provide this section._
173
174- _Describe only the mechanisms and principles that are visible in the development tasks (use or access). Do not provide internal implementation that is invisible to developers._
175
176- _If necessary, use sequence diagrams and flowcharts. Ensure that the text description matches the figure description._
177
178- _Be careful not to disclose internal information._
179
180_**[Writing Requirements]**_
181
182- _Provide clear content. Avoid vague, obscure, and ambiguous expressions._
183
184- _Use only necessary terms, acronyms, abbreviations, and proper nouns, and provide explanations or links to the glossary._
185
186- _Use consistent terms, acronyms, abbreviations, and proper nouns throughout the document._
187
188***[Example]***
189
190The distributed data objects are encapsulated into JS objects in distributed in-memory databases, which allows the distributed data objects to be operated in the same way as local variables. The system automatically implements cross-device data synchronization.
191
192**Figure 1** Working mechanism
193
194![how-distributedobject-works](figures/how-distributedobject-works.png)
195
196### Constraints
197
198_Optional. Describe constraints that are common to all task scenarios._
199
200_**[Developers' Concerns]**_
201
202_What are the constraints for using the kit/solution/feature/function/module? How well is the kit/solution/feature/function/module implemented? Can it meet my requirements?_
203
204_**[Key Writing Points]**_
205
206- _Describe perceptible constraints that affect development activities, including but not limited to the following:_
207  - _Function constraints_
208     - _Application scope of the solution/feature/function/module (Specify scenarios that are not supported.)_
209     - _Specification constraints_
210  - _**Operation constraints**_
211     - _Operations on known issues_
212     - _Potentially risky operations (such as performance deterioration)_
213
214- _Describe operations that are prone to errors in the procedure, but not in this section._
215
216***[Example]***
217
218- This function is available only for XXX devices of XXX and later versions.
219
220- Data synchronization can be implemented across devices only for the applications with the same bundleName.
221
222- Each distributed data object occupies 100 KB to 150 KB of memory. Therefore, you are advised not to create too many distributed data objects.
223
224- The maximum size of a distributed data object is 500 KB.
225
226### Relationship with Other Kits/Solutions/Features/Functions/Modules (Writing Based on the Actual Conditions)
227
228_Optional. Some kits/solutions/features/functions/modules need to be used together with others or have similar or related scenarios. Specify the relationship between them here._
229
230***[Example]***
231
232Asset Store Kit provides secure storage of sensitive data less than 1 KB in size. To protect data greater than 1 KB, use HUKS or Crypto Framework.
233
234### Samples
235
236_Optional. Provide samples that are common to all task scenarios._
237
238_**[Developers' Concerns]**_
239
240_What sample code, codelabs, and demo projects are available?_
241
242_**[Key Writing Points]**_
243
244_Provide links (generally Gitee links) to the released sample code, codelabs, and demo projects. Do not include project packages into the document as an attachment._
245
246***[Example]***
247
248The following sample is provided to help you better understand how to develop abilities:
249
250- [Intra-UIAbility and Inter-UIAbility Page Redirection (ArkTS)](https://gitee.com/openharmony/codelabs/tree/master/Ability/StageAbility)
251
252
253## Setting Up the Environment
254
255_Optional._
256
257_Based on the analysis and breakdown of a specific task scenario, you can place the environment setup content under "Prerequisites" or "Preparations" and close to the "How to Develop" of the specific scenario._
258
259_Specify how to prepare the development environment, including software and hardware configuration requirements, tool requirements, and device requirements._
260
261_Delete this section if no special requirements are involved._
262
263
264### Environment Requirements
265
266_**[Writing Requirements]**_
267
268_Describe the software and hardware configurations required by the development environment so that developers can prepare the environment in advance. You can use subtitles if there is a large amount of content._
269
270***[Example]***
271
272The following table describes the environment configuration requirements specific to the Hi3861 development board.
273
274**Table 1** Hi3861 development environment-specific requirements
275
276| Platform Type| Development Tool| Function| How to Obtain|
277| -------- | -------- | -------- | -------- |
278| Linux server| SCons3.0.4+ | Executes script compilation.| Internet|
279| Linux server| build-essential | Provides a basic software package for compilation and building.| Internet|
280
281
282### Setting Up the Environment
283
284_**[Writing Requirements]**_
285
286_Describe the procedure for setting up the development environment. If there is a large amount of content, use subtitles, for example, "Setting Up the Basic Build Environment" and "Setting Up the Compilation Tool Environment"._
287
288***[Example]***
289
2901. Start a Linux server.
291
2922. Run the following command to install the tool installation package:
293
294   ```
295   xxxxx
296   ```
297
2983. Run the following command to check whether the tool is successfully installed.
299
300   ```
301   xxxxx
302   ```
303
304
305### Verifying the Environment
306
307_**[Writing Requirements]**_
308
309_Provide the criteria for checking whether the environment is set up successfully. You can also provide the criteria along with the environment setup procedure, as provided in the preceding example._
310
311
312## *Example* Overview
313
314_Optional._
315
316- _If the task scenarios and relationships between scenarios of the kit/solution/feature/function/module are not explicitly presented and it is inappropriate to provide the information in the topic "Introduce to *Example*", use this topic to introduce the task scenarios (how they are divided) and describe the relationship between scenarios (when to select each scenario)._
317
318- _If the task scenario is relatively simple, you can briefly describe it in "Introduce to *Example*"._
319
320
321## *Example Task Scenario* Development (Use a specific scenario name. If there is only one scenario, use the solution/feature/function/module name.)
322
323_Mandatory._
324
325_**[Developers' Concerns]**_
326
327_How do I use or access the kit/solution/feature/function/module?_
328
329_**[Key Writing Points]**_
330
331_Provide scenarios that are close to actual development scenarios._
332
333- _Task scenarios are what developers need to use to achieve development objectives._
334
335- _There can be one or more task scenarios. You can use multiple "Development Guidelines" sections. Follow the hierarchical logic when writing the guidelines, that is, a task scenario -> a subtask scenario -> task logic ("Development Process") -> operation procedure ("How to Develop")._
336
337### *Example Task Scenario* Overview
338
339_Optional._
340
341_Describe the contents directly related to a task scenario. In this section, you need to introduce this specific task scenario and describe development roadmap, selection suggestions, concepts, working principles, and constraints. The requirements for writing the concepts and principles are the same as those provided in "Introduction to *Example*." If there is nothing in common, delete it._
342
343### Development Process
344
345_**[Key Writing Points]**_
346
347- _Optional. If there are many development steps (five or more core operations) or complex logical relationships between steps, provide the development process so that developers can have a panoramic view of the operations to be performed._
348
349- _Provide flowcharts and tables if necessary._
350
351
352### Available APIs
353
354_**[Writing Requirements]**_
355
356- _Optional. Describe the key APIs in the development steps and provide the API introduction, so that developers can have a general understanding of development._
357
358- _If there are more than 10 APIs, provide the main APIs only._
359
360- _Ensure that the APIs and their functions of the corresponding version are supported when the document is released._
361
362***[Example]***
363
364The following table lists the key notification interfaces. For details about the APIs, see the API Reference (provide the link to the corresponding API reference).
365
366**Table 1** APIs for notification enabling
367
368| API                                                      | Description            |
369| ------------------------------------------------------------ | ---------------- |
370| isNotificationEnabled(bundle: BundleOption, callback: AsyncCallback\<boolean>): void | Checks whether notification is enabled.|
371| enableNotification(bundle: BundleOption, enable: boolean, callback: AsyncCallback\<void>): void | Sets whether to enable notification.    |
372
373
374### How to Develop
375
376_**[Writing Requirements]**_
377
378_Mandatory._
379
380- _Completeness and Correctness_
381  - _Describe the complete development process (for example, steps related to the code, resources, third-party libraries, and application configuration files in the HAP) so that developers can correctly complete the development. Do not omit key configuration operations._
382  - _Ensure that the code snippet provided in the document can be built with the context in DevEco Studio._
383  - _Ensure that the complete sample code provided in the document can be run in DevEco Studio, and the execution result is the same as that described in the document._
384
385- _Clarity_
386  - _Provide a clear execution owner (who), operation purpose (why), operation content (what/how), and scenario (when/where) for each step. Use imperative sentence to describe steps._
387  - _Clearly provide the APIs (if involved) in steps, as well as their usage description and sample code._
388  - _Provide development suggestions or precautions for key steps and sample code (comments for sample code)._
389       *Think about what questions may be raised when developers are performing the operations.* *These problems are obstacles to developers.* *Provide support information in the document to help them handle these obstacles.* *Examples of support information:*
390     - *Branch selection principle. Provide principles or suggestions for selecting branches and parameters.*
391
392     - *Necessary supplementary description. Describe possible special operations, required operation permissions, high efficiency skills, and concise and clear background knowledge.*
393
394     - *Precautions. Describe operations that may adversely affect other functions or system performance and reliability, and operations that may cause data loss or security problems.* *Provide this type of information in a style different from that of the body prior to the operation procedure.*
395
396     - *Error prevention/correction information. Provide guidance for preventing, locating, or rectifying typical problems that may occur in the development process.* *This type of information can be provided in "How to Develop" or "FAQs", depending on the content amount.*
397
398- _Standardization_
399  - _Provide both logically and syntactically correct sample code and write it in a standard manner. Anonymize sensitive information, such as mobile numbers, ID cards, and account names, for example, 186\*\*\*\*\*\*\*\*. Use private IP addresses or a corresponding format, for example, xx.xx.xx.xx and www.example.com, rather than real IP addresses and domain names._
400  - _Provide code that complies with the code indentation requirements. Do not use the Tab key to indent code. Instead, use four spaces, to avoid incorrect display._
401
402**[Example (Excerpt)]**
403
4041. Import the PhotoPicker module.
405
406   ```javascript
407   import {
408     PhotoPickerComponent,
409     PickerController,
410     ...
411   } from '@kit.MediaLibraryKit';
412   import { photoAccessHelper } from '@ohos.file.PhotoPickerComponent';
413   ```
414
4152. Create a **PickerOptions** instance and a **PickerController** instance for a **Picker** component.
416
417   Through the **PickerOptions** instance, you can configure the grid style (such as the background color of the check box and text color), sliding preview direction, and maximum number of options of the **Picker** component.
418
419   Through the **PickerController** instance, the application can send data to the **Picker** component.
420
421   ```javascript
422   // Set parameters during component initialization.
423   pickerOptions: PickerOptions = new PickerOptions();
424
425   // After the component is initialized, control its behavior.
426   @State pickerController: PickerController = new PickerController();
427   ```
428
429
430### Verification
431
432_**[Writing Requirements]**_
433
434- _Optional. After the development is complete, provide a guide to check whether the operation is successful if there is an independent commissioning and verification operation. The operation procedure is the same as that described in "How to Develop."_
435
436- _Provide only the final service commissioning. You are advised to verify the operation result of each subtask after the development is complete._
437
438
439## FAQs
440
441_Optional._
442
443_**[Developers' Concerns]**_
444
445_What are the typical problems that may occur in the development process of the kit/solution/feature/function/module? How do I locate and solve these problems?_
446
447_**[Key Writing Points]**_
448
449_Describe the problems that may occur during the development and the solutions to them._
450
451- _Delete this section if there are no common problems._
452
453- _It is recommended that common problems in each task scenario be described in a separate chapter. Common problems related to a single task scenario be described in the corresponding chapter._
454
455
456
457### 1. Example question
458
459For details about the template, see [FAQ Template](faq-template.md).
460