diff --git a/docs/ENG-FUNDAMENTALS-CHECKLIST.md b/docs/ENG-FUNDAMENTALS-CHECKLIST.md index 6a7764a7cd..a17dcf4319 100644 --- a/docs/ENG-FUNDAMENTALS-CHECKLIST.md +++ b/docs/ENG-FUNDAMENTALS-CHECKLIST.md @@ -69,7 +69,7 @@ More details on [agile development](agile-development/README.md) ## Design Reviews -- [ ] Process for conducting design reviews is included in the [Working Agreement](agile-development/advanced-topics/team-agreements/working-agreements.md). +- [ ] Process for conducting design reviews is included in the [Working Agreement](agile-development/team-agreements/working-agreements.md). - [ ] Design reviews for each major component of the solution are carried out and documented, including alternatives. - [ ] Stories and/or PRs link to the design document. - [ ] Each user story includes a task for design review by default, which is assigned or removed during sprint planning. @@ -97,7 +97,7 @@ More details on [code reviews](code-reviews/README.md) - [ ] Experiments have owners and are added to project backlog. - [ ] The team conducts longer retrospective for Milestones and project completion. -More details on [retrospectives](agile-development/basics/ceremonies.md#retrospectives) +More details on [retrospectives](agile-development/ceremonies.md#retrospectives) ## Engineering Feedback diff --git a/docs/SPRINT-STRUCTURE.md b/docs/SPRINT-STRUCTURE.md index 4433a1dd42..39802f6c0c 100644 --- a/docs/SPRINT-STRUCTURE.md +++ b/docs/SPRINT-STRUCTURE.md @@ -11,10 +11,10 @@ The purpose of this document is to: ### Before starting the project - [ ] Discuss and start writing the Team Agreements. Update these documents with any process decisions made throughout the project - - [Working Agreement](agile-development/advanced-topics/team-agreements/working-agreements.md) - - [Definition of Ready](agile-development/advanced-topics/team-agreements/definition-of-ready.md) - - [Definition of Done](agile-development/advanced-topics/team-agreements/definition-of-done.md) - - [Estimation](agile-development/basics/ceremonies.md#estimation) + - [Working Agreement](agile-development/team-agreements/working-agreements.md) + - [Definition of Ready](agile-development/team-agreements/definition-of-ready.md) + - [Definition of Done](agile-development/team-agreements/definition-of-done.md) + - [Estimation](agile-development/ceremonies.md#estimation) - [ ] [Set up the repository/repositories](source-control/README.md#creating-a-new-repository) - Decide on repository structure/s - Add [README.md](resources/templates/README.md), [LICENSE](resources/templates/LICENSE), [CONTRIBUTING.md](resources/templates/CONTRIBUTING.md), .gitignore, etc @@ -25,7 +25,7 @@ The purpose of this document is to: ### Day 1 -- [ ] [Plan the first sprint](agile-development/basics/ceremonies.md#sprint-planning) +- [ ] [Plan the first sprint](agile-development/ceremonies.md#sprint-planning) - Agree on a sprint goal, and how to measure the sprint progress - Determine team capacity - Assign user stories to the sprint and split user stories into tasks @@ -42,7 +42,7 @@ The purpose of this document is to: - [ ] [Set up Source Control](source-control/README.md) - Agree on [best practices for commits](source-control/git-guidance/README.md#commit-best-practices) - [ ] [Set up basic Continuous Integration with linters and automated tests](continuous-integration/README.md) -- [ ] [Set up meetings for Daily Stand-ups and decide on a Process Lead](agile-development/basics/ceremonies.md#stand-up) +- [ ] [Set up meetings for Daily Stand-ups and decide on a Process Lead](agile-development/ceremonies.md#stand-up) - Discuss purpose, goals, participants and facilitation guidance - Discuss timing, and how to run an efficient stand-up - [ ] [If the project has sub-teams, set up a Scrum of Scrums](agile-development/advanced-topics/effective-organization/scrum-of-scrums.md) @@ -50,7 +50,7 @@ The purpose of this document is to: ### Day 3 - [ ] [Agree on code style](code-reviews/README.md) and on [how to assign Pull Requests](code-reviews/pull-requests.md) -- [ ] [Set up Build Validation for Pull Requests (2 reviewers, linters, automated tests)](code-reviews/README.md) and agree on [Definition of Done](agile-development/advanced-topics/team-agreements/definition-of-done.md) +- [ ] [Set up Build Validation for Pull Requests (2 reviewers, linters, automated tests)](code-reviews/README.md) and agree on [Definition of Done](agile-development/team-agreements/definition-of-done.md) - [ ] [Agree on a Code Merging strategy](source-control/merge-strategies.md) and update the [CONTRIBUTING.md](resources/templates/CONTRIBUTING.md) - [ ] [Agree on logging and observability frameworks and strategies](observability/README.md) @@ -64,12 +64,12 @@ The purpose of this document is to: ### Day 5 -- [ ] Conduct a [Sprint Demo](agile-development/basics/ceremonies.md#sprint-demo) -- [ ] Conduct a [Retrospective](agile-development/basics/ceremonies.md#retrospectives) +- [ ] Conduct a [Sprint Demo](agile-development/ceremonies.md#sprint-demo) +- [ ] Conduct a [Retrospective](agile-development/ceremonies.md#retrospectives) - Determine required participants, how to capture input (tools) and outcome - Set a timeline, and discuss facilitation, meeting structure etc. - [ ] [Refine the Backlog](agile-development/advanced-topics/backlog-management) - Determine required participants - - Update the [Definition of Ready](agile-development/advanced-topics/team-agreements/definition-of-ready.md) - - Update estimates, and the [Estimation](agile-development/basics/ceremonies.md#estimation) document + - Update the [Definition of Ready](agile-development/team-agreements/definition-of-ready.md) + - Update estimates, and the [Estimation](agile-development/ceremonies.md#estimation) document - [ ] [Submit Engineering Feedback for issues encountered](engineering-feedback/README.md) diff --git a/docs/agile-development/advanced-topics/effective-organization/scrum-of-scrums.md b/docs/agile-development/advanced-topics/effective-organization/scrum-of-scrums.md index fb0b3c9155..c1b5a67d6b 100644 --- a/docs/agile-development/advanced-topics/effective-organization/scrum-of-scrums.md +++ b/docs/agile-development/advanced-topics/effective-organization/scrum-of-scrums.md @@ -1,6 +1,6 @@ # Scrum of Scrums -Scrum of scrums is a technique used to scale Scrum to a larger group working towards the same project goal. In Scrum, we consider a team being too big when going over 10-12 individuals. This should be decided on a case by case basis. If the project is set up in multiple work streams that contain a fixed group of people and a common [stand-up](../../basics/ceremonies.md#stand-up) meeting is slowing down productivity: scrum of scrums should be considered. The team would identify the different subgroups that would act as a separate scrum teams with their own backlog, board and stand-up. +Scrum of scrums is a technique used to scale Scrum to a larger group working towards the same project goal. In Scrum, we consider a team being too big when going over 10-12 individuals. This should be decided on a case by case basis. If the project is set up in multiple work streams that contain a fixed group of people and a common [stand-up](../../ceremonies.md#stand-up) meeting is slowing down productivity: scrum of scrums should be considered. The team would identify the different subgroups that would act as a separate scrum teams with their own backlog, board and stand-up. ## Goals @@ -15,7 +15,7 @@ The scrum of scrums ceremony happens every day and can be seen as a regular stan The outcome of the meeting will result in a list of impediments related to coordination of the whole project. Solutions could be: agreeing on interfaces between teams, discussing architecture changes, evolving responsibility boundaries, etc. -This list of impediments is usually managed in a separate [backlog](../../basics/backlog-management.md) but does not have to. +This list of impediments is usually managed in a separate [backlog](../../backlog-management.md) but does not have to. ## Participation @@ -29,7 +29,7 @@ When choosing to implement Scrum of Scrums, you need to keep in mind that some t ## Measures -The easiest way to measure the impact is by tracking the time to resolve issues in the scrum of scrums backlog. You can also track issues reported during the [retrospective](../../basics/ceremonies.md#retrospectives) related to global coordination (is it well done? can it be improved?). +The easiest way to measure the impact is by tracking the time to resolve issues in the scrum of scrums backlog. You can also track issues reported during the [retrospective](../../ceremonies.md#retrospectives) related to global coordination (is it well done? can it be improved?). ## Facilitation Guidance diff --git a/docs/design/design-reviews/recipes/engagement-process.md b/docs/design/design-reviews/recipes/engagement-process.md index 68999861e7..c338dde9fd 100644 --- a/docs/design/design-reviews/recipes/engagement-process.md +++ b/docs/design/design-reviews/recipes/engagement-process.md @@ -21,7 +21,7 @@ During this time the team uncovers many unknowns, leveraging all new-found infor ## Sprint Planning -In many engagements Microsoft works with customers using a SCRUM agile development process which begins with sprint planning. [Sprint planning](../../../agile-development/basics/ceremonies.md#sprint-planning) is a great opportunity to dive deep into the next set of high priority work. Some key points to address are the following: +In many engagements Microsoft works with customers using a SCRUM agile development process which begins with sprint planning. [Sprint planning](../../../agile-development/ceremonies.md#sprint-planning) is a great opportunity to dive deep into the next set of high priority work. Some key points to address are the following: 1. Identify stories that require design reviews 1. Separate design from implementation for complex stories @@ -48,7 +48,7 @@ The team can follow the same steps from [sprint planning](#sprint-planning) to h ## Sprint Retrospectives -[Sprint retrospectives](../../../agile-development/basics/ceremonies.md#retrospectives) are a great time to check in with the dev team, identify what is working or not working, and propose changes to keep improving. +[Sprint retrospectives](../../../agile-development/ceremonies.md#retrospectives) are a great time to check in with the dev team, identify what is working or not working, and propose changes to keep improving. It is also a great time to check in on design reviews @@ -58,7 +58,7 @@ It is also a great time to check in on design reviews All design artifacts should be treated as a living document. As requirements change or uncover more unknowns the dev crew should retroactively update all design artifacts. Missing this critical step may cause the customer to incur future technical debt. Artifacts that are not up to date are `bugs` in the design. -> **Tip:** Keep your artifacts up to date by adding it to your teams [Definition of Done](../../../agile-development/advanced-topics/team-agreements/definition-of-done.md) for all user stories. +> **Tip:** Keep your artifacts up to date by adding it to your teams [Definition of Done](../../../agile-development/team-agreements/definition-of-done.md) for all user stories. ## Sync Design Reviews diff --git a/docs/design/design-reviews/recipes/engineering-feasibility-spikes.md b/docs/design/design-reviews/recipes/engineering-feasibility-spikes.md index 26e7f2fb87..39f7fd406b 100644 --- a/docs/design/design-reviews/recipes/engineering-feasibility-spikes.md +++ b/docs/design/design-reviews/recipes/engineering-feasibility-spikes.md @@ -89,4 +89,4 @@ Conducting engineering feasibility spikes sets the team and the customer up for - The key purpose of the engineering feasibility spike is learning. - Learning comes from both conducting and sharing insights from spikes. - Use new spike infused learnings to revise, refine, re-prioritize, or create the next set of spikes. -- When spikes are completed, look for new weekly rhythms like adding a ‘risk’ column to the retro board or raising topics at [daily standup](../../../agile-development/basics/ceremonies.md#stand-up) to identify emerging risks. +- When spikes are completed, look for new weekly rhythms like adding a ‘risk’ column to the retro board or raising topics at [daily standup](../../../agile-development/ceremonies.md#stand-up) to identify emerging risks. diff --git a/docs/design/design-reviews/recipes/high-level-design-recipe.md b/docs/design/design-reviews/recipes/high-level-design-recipe.md index 89155d62b8..cbf04f21f3 100644 --- a/docs/design/design-reviews/recipes/high-level-design-recipe.md +++ b/docs/design/design-reviews/recipes/high-level-design-recipe.md @@ -6,7 +6,7 @@ Design at macroscopic level shows the interactions between systems and services ## 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/team-agreements/README.md)). * Attempt to illustrate different personas involved in the use cases and how/which boxes are their entry points. * Prefer pictures over paragraphs. The diagrams aren't intended to generate code, so they should be fairly high level. * Artifacts should indicate the direction of calls (are they outbound, inbound, or bidirectional?) and call out system boundaries where ports might need to be opened or additional infrastructure work may be needed to allow calls to be made. 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 2f2ec965b8..0df2afc8c9 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)). +* 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/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". diff --git a/docs/design/design-reviews/recipes/templates/feature-story-design-review.md b/docs/design/design-reviews/recipes/templates/feature-story-design-review.md index c1ebe86dac..272aaac859 100644 --- a/docs/design/design-reviews/recipes/templates/feature-story-design-review.md +++ b/docs/design/design-reviews/recipes/templates/feature-story-design-review.md @@ -20,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/team-agreements/definition-of-done.md). ## Non-goals / Out-of-Scope diff --git a/docs/design/design-reviews/recipes/templates/milestone-epic-design-review.md b/docs/design/design-reviews/recipes/templates/milestone-epic-design-review.md index db6d2a1f37..acc78a17b2 100644 --- a/docs/design/design-reviews/recipes/templates/milestone-epic-design-review.md +++ b/docs/design/design-reviews/recipes/templates/milestone-epic-design-review.md @@ -14,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/team-agreements/definition-of-done.md). ## Non-goals / Out-of-Scope diff --git a/docs/design/design-reviews/recipes/templates/template-task-design-review.md b/docs/design/design-reviews/recipes/templates/template-task-design-review.md index d9fdb80816..36629e13eb 100644 --- a/docs/design/design-reviews/recipes/templates/template-task-design-review.md +++ b/docs/design/design-reviews/recipes/templates/template-task-design-review.md @@ -21,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/team-agreements/definition-of-done.md). ## Non-goals / Out-of-Scope @@ -30,8 +30,8 @@ ## Proposed Options * Describe the detailed design to accomplish the proposed task. -* What patterns & practices will be used and why were they chosen. -* Were any alternate proposals considered? +* What patterns & practices will be used and why were they chosen. +* Were any alternate proposals considered? * What new components are required to be developed? * Are there any existing components that require updates? * Relevant diagrams (e.g. sequence, component, context, deployment) should be included here. diff --git a/docs/developer-experience/onboarding-guide-template.md b/docs/developer-experience/onboarding-guide-template.md index 962148d190..73640de7d9 100644 --- a/docs/developer-experience/onboarding-guide-template.md +++ b/docs/developer-experience/onboarding-guide-template.md @@ -16,7 +16,7 @@ When developing an onboarding document for a team, it should contain details of ## Team Agreement and Code of Conduct * Include the team's code of conduct or agreement that defines a set of expectation from each team member and how the team has agreed to operate. -* Working Agreement Template - [working agreement](../agile-development/advanced-topics/team-agreements/working-agreements.md) +* Working Agreement Template - [working agreement](../agile-development/team-agreements/working-agreements.md) ## Dev Environment Setup diff --git a/docs/documentation/guidance/project-and-repositories.md b/docs/documentation/guidance/project-and-repositories.md index 5541fc1c57..c4a736493c 100644 --- a/docs/documentation/guidance/project-and-repositories.md +++ b/docs/documentation/guidance/project-and-repositories.md @@ -31,16 +31,16 @@ Some sections in the documentation of the repository might point to the project - [Onboarding](../../developer-experience/onboarding-guide-template.md) - Repository guide - Production, Spikes -- [Team agreements](../../agile-development/advanced-topics/team-agreements/README.md) - - [Team Manifesto](../../agile-development/advanced-topics/team-agreements/team-manifesto.md) +- [Team agreements](../../agile-development/team-agreements/README.md) + - [Team Manifesto](../../agile-development/team-agreements/team-manifesto.md) - Short summary of expectations around the technical way of working and supported mindset in the team. - E.g., ownership, respect, collaboration, transparency. - - [Working Agreement](../../agile-development/advanced-topics/team-agreements/working-agreements.md) + - [Working Agreement](../../agile-development/team-agreements/working-agreements.md) - How we work together as a team and what our expectations and principles are. - E.g., communication, work-life balance, scrum rhythm, backlog management, code management. - - [Definition of Done](../../agile-development/advanced-topics/team-agreements/definition-of-done.md) + - [Definition of Done](../../agile-development/team-agreements/definition-of-done.md) - List of tasks that must be completed to close a user story, a sprint, or a milestone. - - [Definition of Ready](../../agile-development/advanced-topics/team-agreements/definition-of-ready.md) + - [Definition of Ready](../../agile-development/team-agreements/definition-of-ready.md) - How complete a user story should be in order to be selected as candidate for estimation in the sprint planning. - Contributing Guide - Repo structure diff --git a/docs/machine-learning/ml-project-management.md b/docs/machine-learning/ml-project-management.md index 002ee1c1cb..d5a38603a8 100644 --- a/docs/machine-learning/ml-project-management.md +++ b/docs/machine-learning/ml-project-management.md @@ -14,17 +14,17 @@ To learn more about how ISE runs the Agile process for software development team Within this framework, the team follows these Agile ceremonies: - [Backlog management](../agile-development/advanced-topics/backlog-management) -- [Retrospectives](../agile-development/basics/ceremonies.md#retrospectives) +- [Retrospectives](../agile-development/ceremonies.md#retrospectives) - [Scrum of Scrums](../agile-development/advanced-topics/effective-organization/scrum-of-scrums.md) (where applicable) -- [Sprint planning](../agile-development/basics/ceremonies.md#sprint-planning) -- [Stand-ups](../agile-development/basics/ceremonies.md#stand-up) -- [Working agreement](../agile-development/advanced-topics/team-agreements/working-agreements.md) +- [Sprint planning](../agile-development/ceremonies.md#sprint-planning) +- [Stand-ups](../agile-development/ceremonies.md#stand-up) +- [Working agreement](../agile-development/team-agreements/working-agreements.md) ### Notes on Agile process during exploration and experimentation 1. While acknowledging the fact that ML user stories and research spikes are less predictable than software development ones, we strive to have a deliverable for every user story in every sprint. -2. User stories and spikes are usually estimated using [T-shirt sizes](../agile-development/basics/ceremonies.md#estimation) or similar, and not in actual days/hours. +2. User stories and spikes are usually estimated using [T-shirt sizes](../agile-development/ceremonies.md#estimation) or similar, and not in actual days/hours. 3. ML design sessions should be included in each sprint. diff --git a/docs/non-functional-requirements/reliability.md b/docs/non-functional-requirements/reliability.md index 7f727e1251..c5dfb55b32 100644 --- a/docs/non-functional-requirements/reliability.md +++ b/docs/non-functional-requirements/reliability.md @@ -96,4 +96,4 @@ Leverage automated chaos testing to see how things break. You can read this play Writing up a [post-mortem](https://en.wikipedia.org/wiki/Postmortem_documentation) is a great way to document the root causes, and action items for your failures. They're also a great way to track recurring issues, and create a strong case for prioritizing fixes. -This can even be tied into your regular Agile [restrospectives](../agile-development/basics/ceremonies.md#retrospectives). +This can even be tied into your regular Agile [restrospectives](../agile-development/ceremonies.md#retrospectives). diff --git a/docs/source-control/README.md b/docs/source-control/README.md index 0d9676da93..5b9ad770d0 100644 --- a/docs/source-control/README.md +++ b/docs/source-control/README.md @@ -18,7 +18,7 @@ There are many options when working with Source Control. In [ISE](../ISE.md) we ## General Guidance -Consistency is important, so agree to the approach as a team before starting to code. Treat this as a design decision, so include a design proposal and review, in the same way as you would document all design decisions (see [Working Agreements](../agile-development/advanced-topics/team-agreements/working-agreements.md) and [Design Reviews](../design/design-reviews/README.md)). +Consistency is important, so agree to the approach as a team before starting to code. Treat this as a design decision, so include a design proposal and review, in the same way as you would document all design decisions (see [Working Agreements](../agile-development/team-agreements/working-agreements.md) and [Design Reviews](../design/design-reviews/README.md)). ## Creating a new repository