=== READ BEFORE USING THIS TEMPLATE ===
This template is intended to provide ONE framework to organize the content for an engineering design, including but not limited to
-
Key information elements that generally should be captured, in order to provide a comprehensive view of a design
-
A presentation flow that allows readers to easily comprehend and navigate through the document
-
The sections and subsections also serve as a guidance for engineers to conduct their design effort, particularly the critical scopes and problems that need to be addressed in the design phase.
Keep in mind that there is no ONE-SIZE-FITS-ALL solution in engineering.
-
ALL SECTIONS in the template are not applicable to every design effort. It is at the discretion of the authors and design gatekeepers.
-
Customize the design doc structure and add topics/sections as you see fit for your own design needs.
See Design Doc Best Practice (Living Doc)for more discussion.
目录
Sign-off Table
Please ensure to identify and invite ALL APPRORIATE reviewers and approvers.
-
For designs that are self contained within a functional team, reviewers and approvers from within the team are sufficient.
-
For designs that involve XFN collaboration, it is critical to invite XFN approvers/reviewers to ensure the design from a certain functional team and the design's implications on other functional teams are well communicated, aligned and documented in the design phase BEFORE coding efforts begin.
Role Definitions
-
Approver - Stake holders (>=1) and the their approvals are REQUIRED for design sign-off. It is unnecessarily true that EVERY approver needs to approve the ENTIRE content of the document. For example, for a device SW design that involves device/cloud communication protocol, the cloud team only needs to approve the messaging protocol portion of the design.
-
Reviewer - The people whom are good to seek design feedback from.
MIS | Approver / Reviewer | Signed Off |
---|---|---|
approver |
| |
reviewer |
|
Background
A brief description of the background of this design. This section should clearly outline the justifications of this design, specifically, WHY we need to create this new design, WHAT PROBLEMS it intends to address, WHAT RETURNS are expected from this engineering effort.
Overview
A brief overview of the design and solution. The goal is to help readers obtain a high level picture of the entire design without having to delve into the rest of the document, including fundamental design ideas, key technical solutions/innovations adopted by the design, one sentence descriptions for all solutions considered.
Also, use this section to layout the high level flow of content to help readers navigate through the rest of the document.
Design
Goals & Non-Goals
Clarify the design goals and non-goals. It is worth calling out the non-goals, i.e. the problems beyond the scope of your design, or the problems that are seemingly related but actually orthogonal. This will help reviewers focus on the intended problem statement.
Detailed Design
Use this section to capture the full design details. Use your own judgement to organize the content here. Some example topics are
-
Design Assumptions
We ALWAYS need a careful assessment of the validity of the assumptions made into the design, which lays the foundation for all following engineering cost that will be incurred. Over assumption always leads to severe quality issues in the best case. In most cases, the entire design will be in question. -
Design diagrams and descriptions
Use diagrams to support your description. One picture worth a thousand words. Using diagrams effectively helps convey your design ideas to the audience significantly better. Common design diagrams are-
Architecture diagram
How the newly designed module fit into our overall SW architecture -
UML diagrams
Convetional UML standard defines an extensive set of SW design practices and diagrams. For simplicity, the following reduced set of UML diagrams are the mostly commonly used ones that help capture the key design ideas without incurring too many tedious design details.-
Sequence diagram
A representation of how different SW modules interact with each other, and how messages are exchanged between modules. The modules may all reside on device SW
Often used to define call flows between device SW and cloud boundary
-
-
APIs
Generally, we shall keep design doc concise and avoiding "volatile, tedious" details, which are hard to maintain up-to-date in the long run and design doc may not be the best candidate to capture them.
However, for the designs that involve multiple SW modules or multiple teams, a clear definition of key APIs, data formats, argument types, etc. help establish the contract up front and enable parallel XFN development and standalone integration testing within each module/team separately. AGAIN, use your judgement.
Alternatives Considered
Often times, there are more than one candidate solutions to resolve a problem. Use this section to
-
briefly describe the alternative solutions which are considered
-
pros and cons for each solutions, including the final solutions and alternatives
Conclusions
Conclude the design decisions with proper rationales to justify the decisions. Clearly state the trade off considerations.
Metrics
How to evaluate the quality of the design and the associated engineering implementation is a critical question to bear in mind through the entire design phase. Whenever possible, we need to adopt a data driven approach to
-
Feature specific metrics to evaluate the efficancy of the solution.
-
Feature specific stability metrics. E.g. a Lidar driver needs to montior the sampling rate, consistency, crash rate, redundancy SoC switching latency, etc.
-
System performance metrics. E.g. the computation time, RAM footprint, CPU usages
-
Need a path to harvest the metrics from the field operations, test flights or test automations.
If existing SW stack does not offer such capability, the related design and engineering effort needs to be planned and scoped as part of this design.
Test Effort
Design the Testability.
-
Architecturally, strive for modular design with clear APIs.
This allows each module and its upstream/downstream modules to be tested independently. This also means more unit testable -
Design such that the developers can conduct on-bench integration testing in a sustainable and cost-efficient manner.
Avoid one-off testing at all cost. -
Give 2, the testing shall be made automated whenever possible. The related test tooling, scripts, test processes, setups, etc. shall be easily adoptable by QA team to integrate them into the CI/CD infrastructure.
One rule-of-thumb to assess whether or not the design is test friendly one is,
"Can the testing effort be easily integrated into CI/CD to enable continuous verification?"
Similar to Metrics, the testing related engineering effort shall be scoped as part of the design and development work. Developers shall OWN the feature END TO END.
Security & Privacy
Security or privacy implications are discussed here. Include this section when applicable.
Recommendation:
Given the nature of our business, privacy may NOT be a major concern in our current phase. Team shall start developing security mindset for future designs.
Discussions & Future Work
Discuss limitations, trade-offs, potential risks. Also, discuss potential future work if any. For example,
-
some work we don't have a clear business justification now, but may need to revisit in a future date
-
some low priority work we would like to invest in when resource permits, e.g. performance optimziation
Eng Plan
Recommentation
-
For Medium size tasks (2-12 human-weeks), the design owner shall exercise the engineering task break down for a complete scoping. This is also an opportunity for design owners to vet the design and identify the XFN resource gap.
-
For Small size tasks (0-2 human-weeks), generally no eng breakdown is needed
-
For Large size tasks (12+ human-weeks), generally the task itself requires further breakdown of sub-designs. The eng task breandown shall be exercised in the related sub-designs.
Action Item | Owner MIS | Planned ETA | Latest ETA | Comment |
---|---|---|---|---|
References
A bullet point list of reference docs, wikis, public web pages, etc. A quality reference list SHALL provide a full context for the design.