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 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