From 0a5ac1f9a9a03088c60182906219c56a63b418f9 Mon Sep 17 00:00:00 2001 From: Anik Bhattacharjee Date: Mon, 23 Mar 2026 17:04:08 -0400 Subject: [PATCH] Add Design Doc template Additionally, create folder for v0.6.0 design docs Signed-off-by: Anik Bhattacharjee --- design-docs/design-template.md | 102 +++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 design-docs/design-template.md diff --git a/design-docs/design-template.md b/design-docs/design-template.md new file mode 100644 index 000000000..f59501ef2 --- /dev/null +++ b/design-docs/design-template.md @@ -0,0 +1,102 @@ +# Design: _Title here_ +(Sub-Title: _one line description_) + +--- +* Author Name(s): +* Author Date: +* Feedback Due Date: +--- + +## Problem Statement + +``` +Clearly and succinctly write the problem statement. What problem is this design proposing to +solve and who is the intended audience / recipient of the benefit of the solution. + +Describe WHY we need this. Briefly describe the need for this proposed feature to be +built and work be done for it. + +This section focuses on the importance of an idea rather than on whether it is interesting. An +interesting idea is good, but not good enough. This method operates in terms of whether the +idea to be developed is sufficiently important. +``` + +--- + +## Stakeholders +``` +Explicitly identify the stakeholders. Who does this project directly impact? Who has asked that +this work be done? This can range from product managers to other community projects. +Use “personas” and identify an accountable human(usu. PM). +Be as specific as possible. Consult with your stakeholders, get feedback from them. +These are the people who will have to agree on the acceptance criteria (below). + +``` +| Stakeholder | How are they impacted | +| -------------- | --------------------- | +| | | + +--- + +## Acceptance Criteria + +``` +The definition of “done”. What are the specific criteria that when met mean that this feature is +implemented. This must be a very specific goal state or set of definitive verifiable goal states that +define the successful implementation of this feature. +(Think about this as the playbook of the final demonstration showing the desired functionality of this work) +``` + +--- + + +## Solution Design and Architecture + +``` +How do you intend on addressing the need? Describe your main design proposal here and the rationale +behind the decisions you propose. Then lay out the plan of execution, in rough order of how the +execution should take place. Include the rollout plan as well. (This is usually the longest section +of this document!) + +Hint: don’t be afraid of posting arch diagram/other illustrations! The level of detail here has to be +enough to give the reader a clear understanding of the solution - it is up to the writer to decide. +Further detail can be addressed to satisfy comments and increase clarity. +``` + +--- + +## Benefit + +``` +What are the benefits / merits of your proposed design? Tie the benefit directly back into the +solution of the Problem Statement. How does this benefit the client / user? How does the unique approach +yield unique customer benefits? Be specific. Remember, here you are communicating the value +of your proposed design. +``` + +--- + +## Competition (alternatives) + +``` +What other design options were considered? Give an honest treatment of why these alternatives were +not (as) satisfactory. Identify the competition and demonstrate that the competition is clearly +understood. Always consider, what if we do nothing (what are the true / probable consequences)? +``` + +--- + +## Non-goals + +``` +What are you not attempting to do? What is this proposal not about? What is explicity out-of-scope? +``` + +--- + +## Key Dependencies and Open Questions + +``` +What are the open questions that may need to be explored? Be explicit and honest about any +“elephants in the room” and perhaps yet unstated assumptions made. +``` \ No newline at end of file