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 **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 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* Kit 35 36_Mandatory. At the very beginning, describe the basic information about what the kit is, why the kit is needed, and when to use the kit, helping developers have a preliminary understanding of the kit._ 37 38_**[Developers' Concerns]**_ 39 40_What is the 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 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 to support developers in model selection._ 67 68_**[Developers' Concerns]**_ 69 70_What key open capabilities does the kit 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 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? _ 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 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 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 solution/feature/function/module? How well is the 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- Data synchronization can be implemented across devices only for the applications with the same bundleName. 219 220- Each distributed data object occupies 100 KB to 150 KB of memory. Therefore, you are advised not to create too many distributed data objects. 221 222- The maximum size of a distributed data object is 500 KB. 223 224### Relationship with Other Kits 225 226_Optional. Some kits need to be used together with others or have similar or related scenarios. Specify the relationship between the kits here._ 227 228***[Example]*** 229 230Asset 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. 231 232### Samples 233 234_Optional. Provide samples that are common to all task scenarios._ 235 236_**[Developers' Concerns]**_ 237 238_What sample code, codelabs, and demo projects are available?_ 239 240_**[Key Writing Points]**_ 241 242_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._ 243 244***[Example]*** 245 246The following sample is provided to help you better understand how to develop abilities: 247 248- [Intra-UIAbility and Inter-UIAbility Page Redirection (ArkTS)](https://gitee.com/openharmony/codelabs/tree/master/Ability/StageAbility) 249 250 251## Setting Up the Environment 252 253_Optional._ 254 255_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._ 256 257_Specify how to prepare the development environment, including software and hardware configuration requirements, tool requirements, and device requirements._ 258 259_Delete this section if no special requirements are involved._ 260 261 262### Environment Requirements 263 264_**[Writing Requirements]**_ 265 266_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._ 267 268***[Example]*** 269 270The following table describes the environment configuration requirements specific to the Hi3861 development board. 271 272**Table 1** Hi3861 development environment-specific requirements 273 274| Platform Type| Development Tool| Function| How to Obtain| 275| -------- | -------- | -------- | -------- | 276| Linux server| SCons3.0.4+ | Executes script compilation.| Internet| 277| Linux server| build-essential | Provides a basic software package for compilation and building.| Internet| 278 279 280### Setting Up the Environment 281 282_**[Writing Requirements]**_ 283 284_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"._ 285 286***[Example]*** 287 2881. Start a Linux server. 289 2902. Run the following command to install the tool installation package: 291 292 ``` 293 xxxxx 294 ``` 295 2963. Run the following command to check whether the tool is successfully installed. 297 298 ``` 299 xxxxx 300 ``` 301 302 303### Verifying the Environment 304 305_**[Writing Requirements]**_ 306 307_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._ 308 309 310## *Example* Overview 311 312_Optional._ 313 314- _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* Kit", use this topic to introduce the task scenarios (how they are divided) and describe the relationship between scenarios (when to select each scenario)._ 315 316- _If the task scenario is relatively simple, you can briefly describe it in "Introduce to *Example* Kit"._ 317 318 319## *Example Task Scenario* Development (Use a specific scenario name. If there is only one scenario, use the solution/feature/function/module name.) 320 321_Mandatory._ 322 323_**[Developers' Concerns]**_ 324 325_How do I use or access the solution/feature/function/module?_ 326 327_**[Key Writing Points]**_ 328 329_Provide scenarios that are close to actual development scenarios._ 330 331- _Task scenarios are what developers need to use to achieve development objectives._ 332 333- _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")._ 334 335### *Example Task Scenario* Overview 336 337_Optional._ 338 339_Describe the contents directly related to a task scenario. The knowledge points and key writing points are the same as those in "Introduce to *Example* Kit". In this section, you need to introduce this specific task scenario and describe basic concepts, working principles, constraints, and samples that are directly related to the task scenario. If there is nothing in common, delete it._ 340 341### Development Process 342 343_**[Key Writing Points]**_ 344 345- _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._ 346 347- _Provide flowcharts and tables if necessary._ 348 349 350### Available APIs 351 352_**[Writing Requirements]**_ 353 354- _Optional. Describe the key APIs in the development steps and provide the API introduction, so that developers can have a general understanding of development._ 355 356- _If there are more than 10 APIs, provide the main APIs only._ 357 358- _Ensure that the APIs and their functions of the corresponding version are supported when the document is released._ 359 360***[Example]*** 361 362The following table lists the key notification interfaces. For details about the APIs, see the API Reference (provide the link to the corresponding API reference). 363 364**Table 1** APIs for notification enabling 365 366| API | Description | 367| ------------------------------------------------------------ | ---------------- | 368| isNotificationEnabled(bundle: BundleOption, callback: AsyncCallback\<boolean>): void | Checks whether notification is enabled.| 369| enableNotification(bundle: BundleOption, enable: boolean, callback: AsyncCallback\<void>): void | Sets whether to enable notification. | 370 371 372### How to Develop 373 374_**[Writing Requirements]**_ 375 376_Mandatory._ 377 378- _Completeness and Correctness_ 379 - _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._ 380 - _Ensure that the code snippet provided in the document can be built with the context in DevEco Studio._ 381 - _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._ 382 383- _Clarity_ 384 - _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._ 385 - _Clearly provide the APIs (if involved) in steps, as well as their usage description and sample code._ 386 - _Provide development suggestions or precautions for key steps and sample code (comments for sample code)._ 387 *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:* 388 - *Branch selection principle. Provide principles or suggestions for selecting branches and parameters.* 389 390 - *Necessary supplementary description. Describe possible special operations, required operation permissions, high efficiency skills, and concise and clear background knowledge.* 391 392 - *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.* 393 394 - *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.* 395 396- _Standardization_ 397 - _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._ 398 - _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._ 399 400**[Example (Excerpt)]** 401 4021. Import the required modules. 403 404 ```javascript 405 import formBindingData from '@ohos.application.formBindingData' 406 import formInfo from '@ohos.application.formInfo' 407 import formProvider from '@ohos.application.formProvider' 408 ``` 409 4102. Implement the lifecycle callbacks of **LifecycleForm**. 411 412 ```javascript 413 export default { 414 onCreate(want) { 415 console.log('FormAbility onCreate'); 416 // Persistently store widget information for subsequent use, such as widget instance retrieval or update. 417 let obj = { 418 "title": "titleOnCreate", 419 "detail": "detailOnCreate" 420 }; 421 let formData = formBindingData.createFormBindingData(obj); 422 return formData; 423 }, 424 onCastToNormal(formId) { 425 // Called when the widget host converts the temporary widget into a normal one. The widget provider should do something to respond to the conversion. 426 console.log('FormAbility onCastToNormal'); 427 }, 428 } 429 ``` 430 431 432### Verification 433 434_**[Writing Requirements]**_ 435 436- _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."_ 437 438- _Provide only the final service commissioning. You are advised to verify the operation result of each subtask after the development is complete._ 439 440 441## FAQs 442 443_Optional._ 444 445_**[Developers' Concerns]**_ 446 447_What are the typical problems that may occur in the development process of the solution/feature/function/module? How do I locate and solve these problems?_ 448 449_**[Key Writing Points]**_ 450 451_Describe the problems that may occur during the development and the solutions to them._ 452 453- _Delete this section if there are no common problems._ 454 455- _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._ 456 457 458 459### 1. XX problem (simple problem) 460 461XXX 462 463 464### 2. XX problem (complex problem) 465 466**Symptom** 467 468XXX 469 470**Possible Causes** 471 472XXX 473 474**Solution** 475 476XXX 477
