diff --git a/docs/design/design-patterns/README.md b/docs/design/design-patterns/README.md index 3eedb58920..11ea801470 100644 --- 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 index 381bad60dc..0e5373e620 100644 --- 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 index 20c8589788..2f2ec965b8 100644 --- 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/docs/design/design-reviews/recipes/feature-story-design-review-template.md b/docs/design/design-reviews/recipes/templates/feature-story-design-review.md similarity index 92% rename from docs/design/design-reviews/recipes/feature-story-design-review-template.md rename to docs/design/design-reviews/recipes/templates/feature-story-design-review.md index d7014c81e8..c1ebe86dac 100644 --- a/docs/design/design-reviews/recipes/feature-story-design-review-template.md +++ b/docs/design/design-reviews/recipes/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/docs/design/design-reviews/recipes/milestone-epic-design-review-template.md b/docs/design/design-reviews/recipes/templates/milestone-epic-design-review.md similarity index 90% rename from docs/design/design-reviews/recipes/milestone-epic-design-review-template.md rename to docs/design/design-reviews/recipes/templates/milestone-epic-design-review.md index 8c8a21a515..db6d2a1f37 100644 --- a/docs/design/design-reviews/recipes/milestone-epic-design-review-template.md +++ b/docs/design/design-reviews/recipes/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 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/docs/design/design-reviews/recipes/task-design-review-template.md b/docs/design/design-reviews/recipes/templates/template-task-design-review.md similarity index 88% rename from docs/design/design-reviews/recipes/task-design-review-template.md rename to docs/design/design-reviews/recipes/templates/template-task-design-review.md index d7ea572609..d9fdb80816 100644 --- a/docs/design/design-reviews/recipes/task-design-review-template.md +++ b/docs/design/design-reviews/recipes/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/docs/design/design-reviews/recipes/sprint-spike-template.md b/docs/design/design-reviews/recipes/templates/template-technical-spike.md similarity index 96% rename from docs/design/design-reviews/recipes/sprint-spike-template.md rename to docs/design/design-reviews/recipes/templates/template-technical-spike.md index aac4072320..9cb278ba76 100644 --- a/docs/design/design-reviews/recipes/sprint-spike-template.md +++ b/docs/design/design-reviews/recipes/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/docs/design/diagram-types/DesignDiagramsTemplates/Images/azureDeploymentDiagram.png b/docs/design/diagram-types/Templates/Images/azureDeploymentDiagram.png similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/Images/azureDeploymentDiagram.png rename to docs/design/diagram-types/Templates/Images/azureDeploymentDiagram.png diff --git a/docs/design/diagram-types/DesignDiagramsTemplates/Images/deploymentDiagram.png b/docs/design/diagram-types/Templates/Images/deploymentDiagram.png similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/Images/deploymentDiagram.png rename to docs/design/diagram-types/Templates/Images/deploymentDiagram.png diff --git a/docs/design/diagram-types/DesignDiagramsTemplates/Images/ecommerceSite.png b/docs/design/diagram-types/Templates/Images/ecommerceSite.png similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/Images/ecommerceSite.png rename to docs/design/diagram-types/Templates/Images/ecommerceSite.png diff --git a/docs/design/diagram-types/DesignDiagramsTemplates/Images/facebookUserAuthentication.png b/docs/design/diagram-types/Templates/Images/facebookUserAuthentication.png similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/Images/facebookUserAuthentication.png rename to docs/design/diagram-types/Templates/Images/facebookUserAuthentication.png diff --git a/docs/design/diagram-types/DesignDiagramsTemplates/Images/generalization-aggregation-association.png b/docs/design/diagram-types/Templates/Images/generalization-aggregation-association.png similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/Images/generalization-aggregation-association.png rename to docs/design/diagram-types/Templates/Images/generalization-aggregation-association.png diff --git a/docs/design/diagram-types/DesignDiagramsTemplates/Images/orderingSystem.png b/docs/design/diagram-types/Templates/Images/orderingSystem.png similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/Images/orderingSystem.png rename to docs/design/diagram-types/Templates/Images/orderingSystem.png diff --git a/docs/design/diagram-types/DesignDiagramsTemplates/Images/placeOrderScenario.png b/docs/design/diagram-types/Templates/Images/placeOrderScenario.png similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/Images/placeOrderScenario.png rename to docs/design/diagram-types/Templates/Images/placeOrderScenario.png diff --git a/docs/design/diagram-types/DesignDiagramsTemplates/Images/realization.png b/docs/design/diagram-types/Templates/Images/realization.png similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/Images/realization.png rename to docs/design/diagram-types/Templates/Images/realization.png diff --git a/docs/design/diagram-types/DesignDiagramsTemplates/Images/withPersistenceAndSecurity.png b/docs/design/diagram-types/Templates/Images/withPersistenceAndSecurity.png similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/Images/withPersistenceAndSecurity.png rename to docs/design/diagram-types/Templates/Images/withPersistenceAndSecurity.png diff --git a/docs/design/diagram-types/DesignDiagramsTemplates/classDiagrams.md b/docs/design/diagram-types/Templates/classDiagrams.md similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/classDiagrams.md rename to docs/design/diagram-types/Templates/classDiagrams.md diff --git a/docs/design/diagram-types/DesignDiagramsTemplates/componentDiagrams.md b/docs/design/diagram-types/Templates/componentDiagrams.md similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/componentDiagrams.md rename to docs/design/diagram-types/Templates/componentDiagrams.md diff --git a/docs/design/diagram-types/DesignDiagramsTemplates/deploymentDiagrams.md b/docs/design/diagram-types/Templates/deploymentDiagrams.md similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/deploymentDiagrams.md rename to docs/design/diagram-types/Templates/deploymentDiagrams.md diff --git a/docs/design/diagram-types/DesignDiagramsTemplates/sequenceDiagrams.md b/docs/design/diagram-types/Templates/sequenceDiagrams.md similarity index 100% rename from docs/design/diagram-types/DesignDiagramsTemplates/sequenceDiagrams.md rename to docs/design/diagram-types/Templates/sequenceDiagrams.md diff --git a/docs/design/exception-handling/readme.md b/docs/design/exception-handling.md similarity index 100% rename from docs/design/exception-handling/readme.md rename to docs/design/exception-handling.md diff --git a/docs/design/readme.md b/docs/design/readme.md index 1079dea365..485b7792cd 100644 --- 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