diff --git a/docs/code-reviews/recipes/bash.md b/docs/code-reviews/recipes/bash.md index 43eb46326..f4387c7d3 100644 --- a/docs/code-reviews/recipes/bash.md +++ b/docs/code-reviews/recipes/bash.md @@ -6,7 +6,7 @@ Developers should follow [Google's Bash Style Guide](https://google.github.io/st ## Code Analysis / Linting -Projects must check bash code with [shellcheck](https://github.com/koalaman/shellcheck) as part of the [CI process](../../continuous-integration/README.md). +Projects must check bash code with [shellcheck](https://github.com/koalaman/shellcheck) as part of the [CI process](../../CI-CD/continuous-integration.md). Apart from linting, [shfmt](https://github.com/mvdan/sh) can be used to automatically format shell scripts. There are few vscode code extensions which are based on shfmt like shell-format which can be used to automatically format shell scripts. ## Project Setup diff --git a/docs/design/design-patterns/non-functional-requirements-capture-guide.md b/docs/design/design-patterns/non-functional-requirements-capture-guide.md index 21f9e455c..55949f540 100644 --- a/docs/design/design-patterns/non-functional-requirements-capture-guide.md +++ b/docs/design/design-patterns/non-functional-requirements-capture-guide.md @@ -36,7 +36,7 @@ To support the process of capturing a project's _comprehensive_ non-functional r | [Availability](../../non-functional-requirements/availability.md) | System's uptime and accessibility to users. | - Uptime: Uptime measures the percentage of time that a system is operational and available for use. It is typically expressed as a percentage of total time (e.g., 99.9% uptime means the system is available 99.9% of the time). Common thresholds for uptime include:
99% uptime: The system is available 99% of the time, allowing for approximately 3.65 days of downtime per year.
99.9% uptime (three nines): The system is available 99.9% of the time, allowing for approximately 8.76 hours of downtime per year.
99.99% uptime (four nines): The system is available 99.99% of the time, allowing for approximately 52.56 minutes of downtime per year.
99.999% uptime (five nines): The system is available 99.999% of the time, allowing for approximately 5.26 minutes of downtime per year. | | [Data Integrity](../../non-functional-requirements/data-integrity.md) | Accuracy and consistency of data throughout its lifecycle. | - Error Rate: The proportion of data entries that contain errors or inaccuracies. \(\text{Error Rate} = \left( \frac{\text{Number of Errors}}{\text{Total Number of Entries}} \right) \times 100\)
- Accuracy Rate: The percentage of data entries that are correct and match the source of truth. \(\text{Accuracy Rate} = \left( \frac{\text{Number of Accurate Entries}}{\text{Total Number of Entries}} \right) \times 100\)
- Duplicate Record Rate: The percentage of data entries that are duplicates. \(\text{Duplicate Record Rate} = \left( \frac{\text{Number of Duplicate Entries}}{\text{Total Number of Entries}} \right) \times 100\) | | [Disaster recovery and business continuity](../../non-functional-requirements/disaster-recovery.md) | Determine the system's requirements for disaster recovery and business continuity, including backup and recovery procedures and disaster recovery testing. | - Backup and Recovery: The application must have a Backup and Recovery plan in place that includes regular backups of all data and configurations, and a process for restoring data and functionality in the event of a disaster or disruption.
- Redundancy: The application must have Redundancy built into its infrastructure, such as redundant servers, network devices, and power supplies, to ensure high availability and minimize downtime in the event of a failure.
- Failover and high availability: The application must be designed to support Failover and high availability, such as by using load balancers or Failover clusters, to ensure that it can continue to operate in the event of a system failure or disruption.
- Disaster Recovery plan: The application must have a comprehensive disaster Recovery plan that includes procedures for restoring data and functionality in the event of a major disaster, such as a natural disaster, cyber attack, or other catastrophic event.
- Testing and Maintenance: The application must be regularly tested and maintained to ensure that it can withstand a disaster or disruption, and that all systems, processes, and data can be quickly restored and recovered. | -| [Reliability](../../reliability/README.md) | System's ability to maintain functionality under varying conditions and failure scenarios. | - Mean Time Between Failures (MTBF): The system should achieve an MTBF of at least 1000 hours, indicating a high level of reliability with infrequent failures.
- Mean Time to Recover (MTTR): The system should aim for an MTTR of less than 1 hour, ensuring quick recovery and minimal disruption in the event of a failure.
- Redundancy Levels: The system should include redundancy mechanisms to achieve a redundancy level of N+1, ensuring high availability and fault tolerance. | +| [Reliability](../../non-functional-requirements/reliability.md) | System's ability to maintain functionality under varying conditions and failure scenarios. | - Mean Time Between Failures (MTBF): The system should achieve an MTBF of at least 1000 hours, indicating a high level of reliability with infrequent failures.
- Mean Time to Recover (MTTR): The system should aim for an MTTR of less than 1 hour, ensuring quick recovery and minimal disruption in the event of a failure.
- Redundancy Levels: The system should include redundancy mechanisms to achieve a redundancy level of N+1, ensuring high availability and fault tolerance. | ### Performance Requirements @@ -53,7 +53,7 @@ To support the process of capturing a project's _comprehensive_ non-functional r | [Compliance](../../non-functional-requirements/compliance.md) | Adherence to legal, regulatory, and industry standards and requirements. | See [Microsoft Purview Compliance Manager](https://aka.ms/ComplianceManager) | | [Privacy](../../privacy/README.md) | Protection of sensitive information and compliance with privacy regulations. | - Compliance with Privacy Regulations: Achieve full compliance with GDPR, CCPA and HIPAA.
- Data Anonymization: Implement anonymization techniques in protecting individual privacy while still allowing for data analysis.
- Data Encryption: Ensure that sensitive data is encrypted according to encryption standards and best practices.
- User Privacy Preferences: The ability to respect and accommodate user privacy preferences regarding data collection, processing, and sharing. | | [Security](../../security/README.md) | Establish the security requirements of the system, such as authentication, authorization, encryption, and compliance with industry or legal regulations. | See [Threat Modeling Tool](https://aka.ms/tmt) | -| [Sustainability](../../design/sustainability/readme.md) | Ability to operate over an extended period while minimizing environmental impact and resource consumption. | - Energy Efficiency: Kilowatt-hours/Transaction.
- Carbon Footprint: Tons of CO2 emissions per year. | +| [Sustainability](../sustainability/README.md) | Ability to operate over an extended period while minimizing environmental impact and resource consumption. | - Energy Efficiency: Kilowatt-hours/Transaction.
- Carbon Footprint: Tons of CO2 emissions per year. | ### System Maintainability Requirements @@ -68,6 +68,6 @@ To support the process of capturing a project's _comprehensive_ non-functional r | Quality | Attribute |Description | Common Metrics | | -- | -- | -- | -- | -| [Accessibility](../../accessibility/README.md) | The solution must be usable by people with disabilities. Compliance with accessibility standards. Support for assistive technologies | - Alternative Text for Images: All images and non-text content must have alternative text descriptions that can be read by screen readers.
- Color contrast: The application must use color schemes that meet the recommended contrast ratio between foreground and background colors to ensure visibility for users with low vision.
- Focus indicators: The application must provide visible focus indicators to highlight the currently focused element, which is especially important for users who rely on keyboard navigation.
- Captions and Transcripts: All audio and video content must have captions and transcripts, to ensure that users with hearing impairments can access the content.
- Language identification: The application must correctly identify the language of the content, to ensure that screen readers and other assistive technologies can read the content properly. | | +| [Accessibility](../../non-functional-requirements/accessibility.md) | The solution must be usable by people with disabilities. Compliance with accessibility standards. Support for assistive technologies | - Alternative Text for Images: All images and non-text content must have alternative text descriptions that can be read by screen readers.
- Color contrast: The application must use color schemes that meet the recommended contrast ratio between foreground and background colors to ensure visibility for users with low vision.
- Focus indicators: The application must provide visible focus indicators to highlight the currently focused element, which is especially important for users who rely on keyboard navigation.
- Captions and Transcripts: All audio and video content must have captions and transcripts, to ensure that users with hearing impairments can access the content.
- Language identification: The application must correctly identify the language of the content, to ensure that screen readers and other assistive technologies can read the content properly. | | | [Internationalization and Localization](../../non-functional-requirements/internationalization.md) | Adaptation of the software for use in different languages and cultures. Tailoring the software to meet the specific needs of different regions or locales. | - Language and Locale Support: The software's support for different languages, character sets, and locales. Portability requires internationalization and localization efforts to ensure that the software can be used effectively in different regions and cultures, with support for at least five major languages.
- Multi currency: The system's support for multiple currencies, allowing different symbols and conversion rates. | | -| [Usability](../../user-interface-engineering/usability.md) | Intuitiveness, ease of learning, and user satisfaction with the software interface. | - Task Completion Time: The average time it takes for users to complete specific tasks. A user must be able to complete an account settings in less than 2 minutes.
- Ease of Navigation: The ease with which users can navigate through the system and find the information they need. This can be measured by observing user interactions or conducting usability tests.
- User Satisfaction: User satisfaction can be measured using surveys, feedback forms, or satisfaction ratings. A satisfaction score of 70% or higher is typically considered satisfactory.
- Learnability: The ease with which new users can learn to use the system. This can be measured by the time it takes for users to perform basic tasks or by conducting usability tests with novice users. | | +| [Usability](../../non-functional-requirements/usability.md) | Intuitiveness, ease of learning, and user satisfaction with the software interface. | - Task Completion Time: The average time it takes for users to complete specific tasks. A user must be able to complete an account settings in less than 2 minutes.
- Ease of Navigation: The ease with which users can navigate through the system and find the information they need. This can be measured by observing user interactions or conducting usability tests.
- User Satisfaction: User satisfaction can be measured using surveys, feedback forms, or satisfaction ratings. A satisfaction score of 70% or higher is typically considered satisfactory.
- Learnability: The ease with which new users can learn to use the system. This can be measured by the time it takes for users to perform basic tasks or by conducting usability tests with novice users. | | diff --git a/docs/design/design-reviews/recipes/README.md b/docs/design/design-reviews/recipes/README.md index e9920797d..d7b38ce2a 100644 --- a/docs/design/design-reviews/recipes/README.md +++ b/docs/design/design-reviews/recipes/README.md @@ -20,13 +20,13 @@ Design reviews come in all shapes and sizes. There are also different items to c - Design should be more detailed than game plan - May require unique deployment, security and/or privacy characteristics from other milestones -### [Feature / Story Design Review](./feature-story-design-review-template.md) +### [Feature / Story Design Review](./templates/feature-story-design-review.md) - Design for complex features or stories - Will reuse deployment, security and other characteristics defined within game plan or milestone - May require new libraries, OSS or patterns to accomplish goals -### [Task Design Review](./task-design-review-template.md) +### [Task Design Review](./templates/template-task-design-review.md) - Highly detailed design for a complex tasks with many unknowns - Will integrate into higher level feature/component designs diff --git a/docs/design/design-reviews/trade-studies/template.md b/docs/design/design-reviews/trade-studies/template.md index f1abdec9d..952360537 100644 --- a/docs/design/design-reviews/trade-studies/template.md +++ b/docs/design/design-reviews/trade-studies/template.md @@ -36,7 +36,7 @@ The following section should establish the desired capabilities of the solution > **IMPORTANT** This is **not** intended to define outcomes for the design activity itself. It is intended to define the outcomes for the solution being designed. -As mentioned in the [User Interface](../../../user-interface-engineering/README.md) section, if the trade study is analyzing an application development solution, make use of the _persona stories_ to derive desired outcomes. For example, if a persona story exemplifies a certain accessibility requirement, the parallel desired outcome may be "The application must be accessible for people with vision-based disabilities". +As mentioned in the [User Interface](../../../UI-UX/README.md) section, if the trade study is analyzing an application development solution, make use of the _persona stories_ to derive desired outcomes. For example, if a persona story exemplifies a certain accessibility requirement, the parallel desired outcome may be "The application must be accessible for people with vision-based disabilities". ### Evaluation Criteria @@ -70,7 +70,7 @@ If applicable, describe the boundaries from which we have to design the solution #### Accessibility -**Accessibility is never optional**. Microsoft has made a public commitment to always produce accessible applications. For more information visit the official [Microsoft accessibility site](https://www.microsoft.com/accessibility) and read the [Accessibility](../../../accessibility/README.md) page. +**Accessibility is never optional**. Microsoft has made a public commitment to always produce accessible applications. For more information visit the official [Microsoft accessibility site](https://www.microsoft.com/accessibility) and read the [Accessibility](../../../non-functional-requirements/accessibility.md) page. Consider the following prompts when determining application accessibility requirements: diff --git a/docs/developer-experience/onboarding-guide-template.md b/docs/developer-experience/onboarding-guide-template.md index b78281ddf..935d1d4c4 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/team-agreements/working-agreements.md) +* Working Agreement Template - [working agreement](../agile-development/team-agreements/working-agreement.md) ## Dev Environment Setup diff --git a/docs/documentation/guidance/project-and-repositories.md b/docs/documentation/guidance/project-and-repositories.md index 0ad966af2..aec3cd664 100644 --- a/docs/documentation/guidance/project-and-repositories.md +++ b/docs/documentation/guidance/project-and-repositories.md @@ -35,7 +35,7 @@ Some sections in the documentation of the repository might point to the project - [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/team-agreements/working-agreements.md) + - [Working Agreement](../../agile-development/team-agreements/working-agreement.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/team-agreements/definition-of-done.md) @@ -50,7 +50,7 @@ Some sections in the documentation of the repository might point to the project - [Pull Requests](./pull-requests.md) - [Code Review Process](../../code-reviews/README.md) - [Code Review Checklist](../../code-reviews/process-guidance/reviewer-guidance.md) - - [Language Specific Checklists](../../code-reviews/recipes/README.md) + - [Language Specific Checklists](../../code-reviews/recipes/) - [Project Design](../../design/design-reviews/README.md) - [High Level / Game Plan](../../design/design-reviews/recipes/high-level-design-recipe.md) - [Milestone / Epic Design Review](../../design/design-reviews/recipes/milestone-epic-design-review-recipe.md) diff --git a/docs/documentation/tools/automation.md b/docs/documentation/tools/automation.md index 7ba2d0c0e..afca787fe 100644 --- a/docs/documentation/tools/automation.md +++ b/docs/documentation/tools/automation.md @@ -7,7 +7,7 @@ If you want to automate some checks on your Markdown documents, there are severa - [markdown-link-check](https://github.com/tcort/markdown-link-check) to extract links from markdown texts and check whether each link is alive (200 OK) or dead. - [write-good](../../code-reviews/recipes/markdown.md#write-good) to check English prose. - [Docker image for node-markdown-spellcheck](https://github.com/tmaier/docker-markdown-spellcheck), a lightweight docker image to spellcheck markdown files. - - [static code analysis](../../continuous-integration/dev-sec-ops/secret-management/static-code-analysis.md) + - [static code analysis](../../CI-CD/dev-sec-ops/secrets-management/static-code-analysis.md) - [VS Code Extensions](../../code-reviews/recipes/markdown.md#vs-code-extensions) - [Write Good Linter](../../code-reviews/recipes/markdown.md#write-good-linter) to get grammar and language advice while editing a document. @@ -16,7 +16,7 @@ If you want to automate some checks on your Markdown documents, there are severa - Automation - [pre-commit](https://pre-commit.com/) to use Git hook scripts to identify simple issues before submitting our code or documentation for review. - Check [Build validation](../../code-reviews/recipes/markdown.md#build-validation) to automate linting for PRs. - - Check [CI Pipeline for better documentation](../../continuous-integration/markdown-linting/README.md) for a sample pipeline with `markdownlint`, `markdown-link-check` and `write-good`. + - Check [CI Pipeline for better documentation](../../CI-CD/recipes/ci-pipeline-for-better-documentation.md) for a sample pipeline with `markdownlint`, `markdown-link-check` and `write-good`. Sample output: diff --git a/docs/machine-learning/agile-development-considerations-for-ml-projects.md b/docs/machine-learning/agile-development-considerations-for-ml-projects.md index d2a42ce3e..e5f0b6ae8 100644 --- a/docs/machine-learning/agile-development-considerations-for-ml-projects.md +++ b/docs/machine-learning/agile-development-considerations-for-ml-projects.md @@ -18,7 +18,7 @@ Within this framework, the team follows these Agile ceremonies: - [Scrum of Scrums](../agile-development/advanced-topics/effective-organization/scrum-of-scrums.md) (where applicable) - [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) +- [Working agreement](../agile-development/team-agreements/working-agreement.md) ## Agile Process During Exploration and Experimentation diff --git a/docs/source-control/secrets-management.md b/docs/source-control/secrets-management.md index d1ffcc91e..685f7ccad 100644 --- a/docs/source-control/secrets-management.md +++ b/docs/source-control/secrets-management.md @@ -8,6 +8,6 @@ E.g. the following pattern will exclude all files with the extension `.private.c *.private.config ``` -For more details on proper management of credentials and secrets in source control, and handling an accidental commit of secrets to source control, please refer to the [Secrets Management](../continuous-delivery/secrets-management/README.md) document which has further information, split by language as well. +For more details on proper management of credentials and secrets in source control, and handling an accidental commit of secrets to source control, please refer to the [Secrets Management](../CI-CD/dev-sec-ops/secrets-management/README.md) document which has further information, split by language as well. -As an extra security measure, apply [credential scanning](../continuous-integration/dev-sec-ops/secret-management/credential_scanning.md) in your CI/CD pipeline. +As an extra security measure, apply [credential scanning](../CI-CD/dev-sec-ops/secrets-management/credential_scanning.md) in your CI/CD pipeline. diff --git a/docs/the-first-week-of-an-ise-project.md b/docs/the-first-week-of-an-ise-project.md index 273275f87..64629d547 100644 --- a/docs/the-first-week-of-an-ise-project.md +++ b/docs/the-first-week-of-an-ise-project.md @@ -10,13 +10,13 @@ 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/team-agreements/working-agreements.md) + - [Working Agreement](agile-development/team-agreements/working-agreement.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 + - Add README.md, LICENSE, CONTRIBUTING.md, .gitignore, etc - [ ] [Build a Product Backlog](agile-development/advanced-topics/backlog-management) - Set up a project in your chosen project management tool (ex. Azure DevOps) - [INVEST](https://en.wikipedia.org/wiki/INVEST_(mnemonic)) in good User Stories and Acceptance Criteria @@ -50,7 +50,7 @@ The purpose of this document is to: - [ ] [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/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 a Code Merging strategy](source-control/merge-strategies.md) and update the CONTRIBUTING.md - [ ] [Agree on logging and observability frameworks and strategies](observability/README.md) ## Day 4