Skip to main content

xxx Subsystem/Module Development Guide

Note:

1. This template provides a writing framework for development guide documents. Requirement scenario analysis should be completed first, then use this template for writing.

2. Italic text represents writing guidance and should be deleted from the final document.

【Overall Writing Requirements】

1. Identify the target audience: Clearly identify the intended audience: developers/product managers/architects.

2. Confirm content to include: Introduce what the feature/module is (What), what it can do (Why), and how to develop it (How).

3. Take the developer's perspective: From a developer’s point of view, provide the relevant and necessary content for development.

4. Task-oriented writing: Focus on the tasks developers need to complete, with practical guidance.

5. Do not be restricted: This template is for reference only. Adjust flexibly according to actual needs.

Introduction to xxx (Specific Feature/Module Name)​

Required.

Clearly describe the basics such as what and why to help developers gain an initial understanding of the feature/module.

【Developer Focus】

What is this feature/module (definition – what)? What problems does it solve or what value does it bring (customer value – why)?

【Writing Tips】

Refer to scenario-based writing, using the SCQA approach as follows:

  • S: situation – start with a familiar situation or fact.
  • C: complication – describe the mismatch between reality and expectations.Highlight the mismatch between reality and expectations.
  • Q: question – How?
  • A: answer – Our solution is...

【Writing Requirements】

  • Only use necessary terms, acronyms, or proprietary names and provide explanations (or link to a glossary).

Functional Features​

Optional.

Describe the key capabilities of this feature/module to assist in selection.

【Developer Focus】

What key functions does this feature/module provide?

【Writing Requirements】

  • Only use necessary terms, acronyms, or proprietary names and provide explanations (or link to a glossary).

Advantages​

Optional.

Describe the advantages of this feature/module compared to similar industry capabilities to assist in selection.

【Developer Focus】

What advantages does this feature/module have?

【Writing Tips】

  • Highlight appealing advantages without exaggeration.

【Writing Requirements】

  • Only use necessary terms, acronyms, or proprietary names and provide explanations (or link to a glossary).

Prerequisite Concepts​

Optional.

【Developer Focus】

What concepts must be understood before using this feature/module?

【Writing Tips】

  • Concepts developers should understand before using this guide.
  • If the concepts have complex logical relationships, consider adding diagrams for clarification.

【Writing Requirements】

  • Only use necessary terms, acronyms, or proprietary names and provide explanations (or link to a glossary).

【Writing Example】

Before using the Cloud Container Engine, developers should understand the following basic concepts:

  • Pod
    A Pod is the smallest deployable unit created or managed by Kubernetes.

  • Container
    Containers originated from Linux and are a form of kernel-level virtualization technology.

Implementation Principles​

Optional.

【Developer Focus】

How does this feature/module work? Understanding the principles helps better usage.

【Writing Tips】

  • Prefer diagrams (e.g., flowcharts, architecture diagrams) where appropriate.
  • Do not disclose confidential information.

【Writing Requirements】

  • Only use necessary terms, acronyms, or proprietary names and provide explanations (or link to a glossary).

Usage Limitations​

Optional.

【Developer Focus】

Are there any limitations when using this feature/module?

【Writing Tips】

  • Describe limitations that may affect development. Example:
  • Functional Limitations
    • Unsupported usage scenarios.
    • Specification limits.

【Writing Example】

  • This feature is available from version XXX and above.

  • Each object must not exceed 100 KB.

Optional.

If the feature/module has strong dependencies or associations with others, clarify them here.

【Writing Tips】

  • Use diagrams where necessary (e.g., architecture, flow).

Environment Preparation​

Optional.

Clearly state the development environment requirements (e.g., hardware, software, OS).

Environment Setup​

【Writing Requirements】

Step-by-step instructions for setting up the development environment.
Include how to verify if the setup was successful.

【Writing Example】

  1. Log into the Linux server terminal via SSH.

  2. Install basic packages using the following command:

xxxxx
  1. Check installation version using the following command:
xxxxx

Development Process​

【Writing Tips】

Optional.

  • How can developers use this feature/module (How)?

  • Follow a layered structure: Scenario (task) → Task Logic (development flow) → Step-by-step instructions.

  • If there are many steps, provide a flowchart.

API Description​

【Writing Requirements】

Optional.

  • Describe key APIs involved in the development process. Use hyperlinks where possible.

Development Steps​

【Writing Requirements】

Required.

  • Each step should include: executor (who), purpose (why), operation (what/how), and context (when/where). Use imperative sentences.

  • Ensure sample code is executable.

  • Provide guidance on how to verify successful execution.

  • Mask sensitive data like phone numbers, ID numbers, or account names, e.g., 186********. Use generic IP addresses or domain names (e.g., xx.xx.xx.xx, www.example.com); do not use real IPs or domains.

Self-Testing​

Optional.

【Writing Tips】

  1. Test environment setup.
  2. Test steps.
  3. Expected results.
  4. (Optional) Common issues and troubleshooting.

Optional.

Other general-use related examples.

【Developer Focus】

Are there any sample code or demos for further learning?

【Writing Tips】

Provide links to released sample code or demos.

Debugging and Diagnostic Tools​

Optional.

【Writing Tips】

  • Debugging and diagnostic tools help developers quickly locate and resolve problems during development, testing, or runtime.
  • Provide hyperlinks if possible.

FAQs​

Optional.

【Developer Focus】

Common issues encountered during development.

【Writing Tips】

Describe various issues encountered during development and their solutions to improve efficiency.

For writing templates, refer to FAQ Template.

Next Steps​

【Writing Tips】

Use a bulleted list (no more than 5 items) to suggest topics developers may be interested in exploring next.