Refactor design (#1059)

* refactor design section * refactor design section * uppercase README * add links * fix links
microsoft · Aug 19, 2024 · d2b1a7e · d2b1a7e
1 parent 7fc5573
commit d2b1a7e
Show file tree

Hide file tree

Showing 22 changed files with 19 additions and 45 deletions.
diff --git a/docs/design/design-patterns/README.md b/docs/design/design-patterns/README.md
@@ -3,13 +3,3 @@
 The design patterns section recommends patterns of software and architecture design.
 This section provides a curated list of commonly used patterns from trusted sources.
 Rather than duplicate or replace the cited sources, this section aims to compliment them with suggestions, guidance, and learnings based on firsthand experiences.
-
-## Subsections
-
-* [Data Heavy Design Guidance](data-heavy-design-guidance.md)
-* [Object Oriented Design Reference](object-oriented-design-reference.md)
-* [Distributed System Design Reference](distributed-system-design-reference.md)
-* [REST API Design Guidance](rest-api-design-guidance.md)
-* [Cloud Resource Design Guidance](cloud-resource-design-guidance.md)
-* [Network Architecture Guidance for Azure](network-architecture-guidance-for-azure.md)
-* [Network Architecture Guidance for Hybrid](network-architecture-guidance-for-hybrid.md)
diff --git a/docs/design/design-reviews/README.md b/docs/design/design-reviews/README.md
@@ -1,14 +1,5 @@
 # Design Reviews
 
-## Table of Contents
-
-- [Goals](#goals)
-- [Measures](#measures)
-- [Impact](#impact)
-- [Participation](#participation)
-- [Facilitation Guidance](#facilitation-guidance)
-- [Technical Spike](#technical-spike)
-
 ## Goals
 
 - Reduce technical debt for our customers
@@ -53,9 +44,6 @@ There is also a healthy balancing act in supporting a healthy debate while not h
 
 The dev crew should always participate in all design review sessions
 
-- [ISE](../../ISE.md) Engineering
-- Customer Engineering
-
 ### Domain Experts
 
 Domain experts should participate in design review sessions as needed

diff --git a/docs/design/design-reviews/recipes/milestone-epic-design-review-recipe.md b/docs/design/design-reviews/recipes/milestone-epic-design-review-recipe.md
@@ -6,7 +6,7 @@ Design at epic/milestone level can help the team make better decisions about pri
 
 ## Things to keep in mind
 
-* As with all other aspects of the project, design reviews must provide a friendly and safe environment so that any team member feels comfortable proposing a design for review and can use the opportunity to grow and learn from the constructive / non-judgemental feedback from peers and subject-matter experts (see [Team Agreements](../../../agile-development/advanced-topics/team-agreements/README.md)).
+* As with all other aspects of the project, design reviews must provide a friendly and safe environment so that any team member feels comfortable proposing a design for review and can use the opportunity to grow and learn from the constructive / non-judgemental feedback from peers and subject-matter experts (see [Team Agreements](../../../agile-development/advanced-topics/team-agreements)).
 * Design reviews should be lightweight and should not feel like an additional process overhead.
 * Dev Lead can usually provide guidance on whether a given epic/milestone needs a design review and can help other team members in preparation.
 * This is *not* a strict template that must be followed and teams should not be bogged down with polished "design presentations".
@@ -16,4 +16,4 @@ Design at epic/milestone level can help the team make better decisions about pri
 
 ## Template
 
-You can download the **[Milestone/Epic Design Review Template](./milestone-epic-design-review-template.md)**, copy it into your project, and use it as described in the [async design review recipe](./async-design-reviews.md).
+You can download the **[Milestone/Epic Design Review Template](./templates/milestone-epic-design-review.md)**, copy it into your project, and use it as described in the [async design review recipe](./async-design-reviews.md).
diff --git a/...s/feature-story-design-review-template.md → .../templates/feature-story-design-review.md b/...s/feature-story-design-review-template.md → .../templates/feature-story-design-review.md
@@ -1,4 +1,6 @@
-# Your Feature or Story Design Title Here (prefix with DRAFT/WIP to indicate level of completeness)
+# Template: Feature / Story Design Review
+
+**Your Feature or Story Design Title Here (prefix with DRAFT/WIP to indicate level of completeness)**
 
 > Does the feature re-use or extend existing patterns / interfaces that have already been established for the project?
 > Does the feature expose new patterns or interfaces that will establish a new standard for new future development?
@@ -18,7 +20,7 @@
 ## Goals/In-Scope
 
 * List the goals that the feature/story will help us achieve that are most relevant for the design review discussion.
-* This should include acceptance criteria required to meet [definition of done](../../../agile-development/advanced-topics/team-agreements/definition-of-done.md).
+* This should include acceptance criteria required to meet [definition of done](../../../../agile-development/advanced-topics/team-agreements/definition-of-done.md).
 
 ## Non-goals / Out-of-Scope
 

diff --git a/.../milestone-epic-design-review-template.md → ...templates/milestone-epic-design-review.md b/.../milestone-epic-design-review-template.md → ...templates/milestone-epic-design-review.md
@@ -1,6 +1,8 @@
-# Your Milestone/Epic Design Title Here (prefix with DRAFT/WIP to indicate level of completeness)
+# Template: Milestone / Epic Design Review
 
-> Please refer to <https://microsoft.github.io/code-with-engineering-playbook/design/design-reviews/recipes/milestone-epic-design-review-recipe/> for things to keep in mind when using this template.
+**Your Milestone/Epic Design Title Here (prefix with DRAFT/WIP to indicate level of completeness)**
+
+> Please refer to the [milestone/epic design review recipe](../milestone-epic-design-review-recipe.md) for things to keep in mind when using this template.
 
 * Milestone / Epic: [Name](http://link-to-work-item)
 * Project / Engagement: [Project Engagement]
@@ -12,7 +14,7 @@
 
 ## Goals / In-Scope
 
-> List a few bullet points of goals that this milestone/epic will achieve and that are most relevant for the design review discussion. You may include acceptable criteria required to meet the [Definition of Done](../../../agile-development/advanced-topics/team-agreements/definition-of-done.md).
+> List a few bullet points of goals that this milestone/epic will achieve and that are most relevant for the design review discussion. You may include acceptable criteria required to meet the [Definition of Done](../../../../agile-development/advanced-topics/team-agreements/definition-of-done.md).
 
 ## Non-goals / Out-of-Scope
 

diff --git a/...ws/recipes/task-design-review-template.md → .../templates/template-task-design-review.md b/...ws/recipes/task-design-review-template.md → .../templates/template-task-design-review.md
@@ -1,6 +1,8 @@
-# Your Task Design Title Here (prefix with DRAFT/WIP to indicate level of completeness)
+# Template: Task Design Review
 
-> When developing a design document for a new task, it should contain a detailed design proposal demonstrating how it will solve the goals outlined below.  
+**Your Task Design Title Here (prefix with DRAFT/WIP to indicate level of completeness)**
+
+> When developing a design document for a new task, it should contain a detailed design proposal demonstrating how it will solve the goals outlined below.
 > Not all tasks require a design review, but when they do it is likely that there many unknowns, or the solution may be more complex.
 > The design should include diagrams, pseudocode, interface contracts as needed to provide a detailed understanding of the proposal.
 
@@ -19,7 +21,7 @@
 ## Goals/In-Scope
 
 * List a few bullet points of what this task will achieve and that are most relevant for the design review discussion.
-* This should include acceptance criteria required to meet the [definition of done](../../../agile-development/advanced-topics/team-agreements/definition-of-done.md).
+* This should include acceptance criteria required to meet the [definition of done](../../../../agile-development/advanced-topics/team-agreements/definition-of-done.md).
 
 ## Non-goals / Out-of-Scope
 

diff --git a/...-reviews/recipes/sprint-spike-template.md → ...pes/templates/template-technical-spike.md b/...-reviews/recipes/sprint-spike-template.md → ...pes/templates/template-technical-spike.md
@@ -1,4 +1,6 @@
-# Spike: {Name}
+# Template: Technical Spike
+
+**Spike: {Name}**
 
 - **Conducted by:** {Names and at least one email address for follow-up questions}
 - **Backlog Work Item:** {Link to the work item to provide more context}

diff --git a/...mplates/Images/azureDeploymentDiagram.png → ...mplates/Images/azureDeploymentDiagram.png b/...mplates/Images/azureDeploymentDiagram.png → ...mplates/Images/azureDeploymentDiagram.png
diff --git a/...amsTemplates/Images/deploymentDiagram.png → ...es/Templates/Images/deploymentDiagram.png b/...amsTemplates/Images/deploymentDiagram.png → ...es/Templates/Images/deploymentDiagram.png
diff --git a/...iagramsTemplates/Images/ecommerceSite.png → ...-types/Templates/Images/ecommerceSite.png b/...iagramsTemplates/Images/ecommerceSite.png → ...-types/Templates/Images/ecommerceSite.png
diff --git a/...tes/Images/facebookUserAuthentication.png → ...tes/Images/facebookUserAuthentication.png b/...tes/Images/facebookUserAuthentication.png → ...tes/Images/facebookUserAuthentication.png
diff --git a/...eneralization-aggregation-association.png → ...eneralization-aggregation-association.png b/...eneralization-aggregation-association.png → ...eneralization-aggregation-association.png
diff --git a/...agramsTemplates/Images/orderingSystem.png → ...types/Templates/Images/orderingSystem.png b/...agramsTemplates/Images/orderingSystem.png → ...types/Templates/Images/orderingSystem.png
diff --git a/...msTemplates/Images/placeOrderScenario.png → ...s/Templates/Images/placeOrderScenario.png b/...msTemplates/Images/placeOrderScenario.png → ...s/Templates/Images/placeOrderScenario.png
diff --git a/...nDiagramsTemplates/Images/realization.png → ...am-types/Templates/Images/realization.png b/...nDiagramsTemplates/Images/realization.png → ...am-types/Templates/Images/realization.png
diff --git a/...tes/Images/withPersistenceAndSecurity.png → ...tes/Images/withPersistenceAndSecurity.png b/...tes/Images/withPersistenceAndSecurity.png → ...tes/Images/withPersistenceAndSecurity.png
diff --git a/.../DesignDiagramsTemplates/classDiagrams.md → .../diagram-types/Templates/classDiagrams.md b/.../DesignDiagramsTemplates/classDiagrams.md → .../diagram-types/Templates/classDiagrams.md
diff --git a/...ignDiagramsTemplates/componentDiagrams.md → ...gram-types/Templates/componentDiagrams.md b/...ignDiagramsTemplates/componentDiagrams.md → ...gram-types/Templates/componentDiagrams.md
diff --git a/...gnDiagramsTemplates/deploymentDiagrams.md → ...ram-types/Templates/deploymentDiagrams.md b/...gnDiagramsTemplates/deploymentDiagrams.md → ...ram-types/Templates/deploymentDiagrams.md
diff --git a/...signDiagramsTemplates/sequenceDiagrams.md → ...agram-types/Templates/sequenceDiagrams.md b/...signDiagramsTemplates/sequenceDiagrams.md → ...agram-types/Templates/sequenceDiagrams.md
diff --git a/docs/design/exception-handling/readme.md → docs/design/exception-handling.md b/docs/design/exception-handling/readme.md → docs/design/exception-handling.md
diff --git a/docs/design/readme.md b/docs/design/readme.md
@@ -11,18 +11,6 @@ This covers not only technical design of software, but also architecture design
 - Reference or define process or checklists to help ensure well-designed software.
 - Collate and point to reference sources (guides, repos, articles) that can help shortcut the learning process.
 
-## Sections
-
-- [Diagram Types](diagram-types/README.md)
-- [Design Patterns](design-patterns/README.md)
-- [Design Reviews](design-reviews/README.md)
-- [Non-Functional Requirements Guidance](design-patterns/non-functional-requirements-capture-guide.md)
-- [Sustainable Software Engineering](sustainability/readme.md)
-
-## Recipes
-
-- [Design Recipes](design-reviews/recipes/README.md)
-
 ## Code Examples
 
 - Folder Structure