# microsoft/code-with-engineering-playbook

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/microsoft-code-with-engineering-playbook).**

2,608 stars · 663 forks · Dockerfile · cc-by-4.0

## Links

- GitHub: https://github.com/microsoft/code-with-engineering-playbook
- Homepage: https://microsoft.github.io/code-with-engineering-playbook/
- awesome-repositories: https://awesome-repositories.com/repository/microsoft-code-with-engineering-playbook.md

## Description

This project is a software engineering playbook providing a collection of standardized guidelines and processes for managing the full software development lifecycle and team operations. It serves as a high-level framework for organizing agile project management, API design, containerized development standards, and markdown documentation workflows.

The framework establishes a system for language-agnostic API design to automate client library generation and documentation. It also defines standards for providing uniform contributor environments and toolchains through virtualized containers.

The playbook covers a broad range of engineering operations, including agile workflow management, software defect tracking, and technical governance. It details processes for architecture decision records, engineering practice standardization, and the use of version-controlled wikis to maintain a single source of truth across repositories.

The technical content pipeline integrates automated quality guardrails, such as markdown linting and link validation, with static site generation and cloud infrastructure provisioning for hosting documentation.

## Tags

### Software Engineering & Architecture

- [Software Engineering Standards](https://awesome-repositories.com/f/software-engineering-architecture/software-engineering-standards.md) — Serves as a comprehensive collection of standardized guidelines and processes for the full software development lifecycle.
- [Agile Project Management](https://awesome-repositories.com/f/software-engineering-architecture/agile-project-management.md) — Provides a structured framework and methodologies for organizing work cycles and delivery timelines using agile project management. ([source](https://cdn.jsdelivr.net/gh/microsoft/code-with-engineering-playbook@main/README.md))
- [API Design Patterns](https://awesome-repositories.com/f/software-engineering-architecture/api-design-patterns.md) — Establishes language-agnostic patterns for defining HTTP service interfaces and automating client library generation.
- [API Design Standards](https://awesome-repositories.com/f/software-engineering-architecture/api-design-standards.md) — Provides guidelines and processes for enforcing consistent API design patterns across multi-team developments. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/guidance/rest-apis/))
- [API Specification Definitions](https://awesome-repositories.com/f/software-engineering-architecture/api-specification-definitions.md) — Implements standardized processes for defining HTTP service interfaces to automate documentation and client library generation. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/guidance/rest-apis/))
- [Architecture Decision Records](https://awesome-repositories.com/f/software-engineering-architecture/architecture-decision-records.md) — Uses structured templates for capturing architecture decision records and trade studies to preserve technical context.
- [Contribution Workflows](https://awesome-repositories.com/f/software-engineering-architecture/contribution-workflows.md) — Defines standardized rules for branching, commits, and pull requests to maintain project history. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/guidance/project-and-repositories/))
- [Agile Workflows](https://awesome-repositories.com/f/software-engineering-architecture/development-methodologies/software-development-lifecycle/agile-workflows.md) — Organizes development work through iterative sprints and backlogs for incremental delivery. ([source](https://cdn.jsdelivr.net/gh/microsoft/code-with-engineering-playbook@main/README.md))
- [Engineering Best Practices](https://awesome-repositories.com/f/software-engineering-architecture/engineering-best-practices.md) — Provides a framework of curated development guidelines to increase software quality across the lifecycle. ([source](https://cdn.jsdelivr.net/gh/microsoft/code-with-engineering-playbook@main/README.md))
- [Language-Agnostic APIs](https://awesome-repositories.com/f/software-engineering-architecture/language-agnostic-apis.md) — Utilizes language-agnostic API specifications to automate the generation of client libraries and documentation.
- [Project Documentation Standards](https://awesome-repositories.com/f/software-engineering-architecture/project-documentation-standards.md) — Defines a consistent set of required documentation artifacts for repositories, commit messages, and APIs. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/))
- [Technical Foundation Standards](https://awesome-repositories.com/f/software-engineering-architecture/technical-foundation-standards.md) — Establishes standardized requirements and benchmarks for security, observability, and testing to ensure consistent system scalability. ([source](https://cdn.jsdelivr.net/gh/microsoft/code-with-engineering-playbook@main/README.md))
- [Code Documentation Standards](https://awesome-repositories.com/f/software-engineering-architecture/code-documentation-standards.md) — Establishes a practice for explaining complex implementation reasoning through internal code documentation. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/guidance/code/))
- [Team Operating Agreements](https://awesome-repositories.com/f/software-engineering-architecture/team-operating-agreements.md) — Establishes formal communication norms and shared definitions of done to align team expectations. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/guidance/project-and-repositories/))
- [Feedback & Issue Standards](https://awesome-repositories.com/f/software-engineering-architecture/technical-reference-manuals/technical-quality-criteria/feedback-issue-standards.md) — Defines requirements for actionable details and reproduction assets in technical reports and issue tracking. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/guidance/engineering-feedback/))

### Content Management & Publishing

- [Technical Documentation](https://awesome-repositories.com/f/content-management-publishing/documentation-knowledge-management/technical-documentation.md) — Implements consistent formatting and organization standards for repositories and APIs to ensure reliable knowledge sharing. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/))
- [Static-Site-Based Documentation](https://awesome-repositories.com/f/content-management-publishing/static-site-document-generators/static-site-generators/content-delivery-publishing/static-site-based-documentation.md) — Implements a technical content pipeline using Git for versioning and static site generation for deployment.
- [Documentation Style Standards](https://awesome-repositories.com/f/content-management-publishing/content-management-systems/content-architecture-modeling/documentation-standards/documentation-style-standards.md) — Applies linguistic and structural style guidelines and review checklists to ensure clear technical writing. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/best-practices/good-documentation/))
- [Documentation Generators](https://awesome-repositories.com/f/content-management-publishing/content-management-systems/content-architecture-modeling/documentation-tooling/generation-publishing/documentation-generators.md) — Automates the creation of technical guides by extracting information from source code comments. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/recipes/using-docfx-and-tools/))
- [Documentation Site Hosting](https://awesome-repositories.com/f/content-management-publishing/content-management-systems/content-architecture-modeling/documentation-tooling/generation-publishing/documentation-site-hosting.md) — Generates static documentation sites and uploads them to cloud hosting services for public accessibility. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/))
- [Document Quality Validations](https://awesome-repositories.com/f/content-management-publishing/document-quality-validations.md) — Automates documentation quality maintenance through integrated validation tools and real-time notifications. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/))
- [Versioned Wikis](https://awesome-repositories.com/f/content-management-publishing/documentation-knowledge-management/wiki-engines/versioned-wikis.md) — Implements a version-controlled wiki system that allows multiple contributors to collaborate on project information. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/tools/wikis/))
- [Wiki Mirroring](https://awesome-repositories.com/f/content-management-publishing/documentation-knowledge-management/wiki-engines/versioned-wikis/wiki-mirroring.md) — Synchronizes wiki content between repositories using git remotes to ensure a secondary backup and consistent knowledge base. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/recipes/sync-wiki-between-repos/))
- [Static Documentation Generation](https://awesome-repositories.com/f/content-management-publishing/static-site-document-generators/static-site-generators/static-documentation-generation.md) — Provides a system to transform text-based source files into searchable technical documentation sites. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/))
- [Static Site Generation](https://awesome-repositories.com/f/content-management-publishing/static-site-document-generators/static-site-generators/static-site-generation.md) — Transforms raw markdown files into a structured documentation website via automated build pipelines.

### Development Tools & Productivity

- [API Documentation Generators](https://awesome-repositories.com/f/development-tools-productivity/api-documentation-generators.md) — Produces programming guides and specifications automatically using specialized comments on types and members. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/guidance/code/))
- [Container Development Environments](https://awesome-repositories.com/f/development-tools-productivity/container-development-environments.md) — Standardizes contributor toolchains and development setups using virtualized container environments.
- [Containerized Development Environments](https://awesome-repositories.com/f/development-tools-productivity/container-development-environments/containerized-development-environments.md) — Provides standardized contributor environments by packaging the entire development stack within virtualized containers. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/best-practices/automation/))
- [Version-Controlled Documentation](https://awesome-repositories.com/f/development-tools-productivity/version-controlled-documentation.md) — Manages technical content using source control and pull requests to facilitate peer reviews and auditability. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/best-practices/establish-and-manage/))
- [Wiki Content Mirroring](https://awesome-repositories.com/f/development-tools-productivity/git-repository-integrators/git-repository-integrators/wiki-content-mirroring.md) — Synchronizes documentation across multiple repositories using git remotes to ensure a single source of truth.
- [Documentation Link Checkers](https://awesome-repositories.com/f/development-tools-productivity/link-validation-tools/documentation-link-checkers.md) — Includes automated tools to scan documentation for broken external hyperlinks and orphaned media. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/recipes/using-docfx-and-tools/))
- [Pull Request Templates](https://awesome-repositories.com/f/development-tools-productivity/project-scaffolding-config-code-generation/project-scaffolding-configuration/repository-templates/pull-request-templates.md) — Uses metadata templates for pull requests to ensure consistent inclusion of descriptions and linked work items. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/guidance/pull-requests/))
- [Cross-Repository Content Synchronization](https://awesome-repositories.com/f/development-tools-productivity/repository-configuration-utilities/cross-repository-content-synchronization.md) — Provides a method for mirroring wiki pages across repositories to maintain shared guidelines in a single source of truth. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/))
- [Work Item Definitions](https://awesome-repositories.com/f/development-tools-productivity/working-copy-management/work-item-traceability/work-item-definitions.md) — Provides standardized attributes and schemas for stories and tasks to ensure shared understanding of scope. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/guidance/work-items/))
- [Hierarchies](https://awesome-repositories.com/f/development-tools-productivity/working-copy-management/work-item-traceability/work-item-definitions/hierarchies.md) — Defines a tiered organizational system for grouping work items into epics and features for business deliverables. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/guidance/work-items/))

### DevOps & Infrastructure

- [Containerized Development Environments](https://awesome-repositories.com/f/devops-infrastructure/containerized-development-environments.md) — Standardizes contributor environments and toolchains through the use of virtualized containers.
- [Git-Based](https://awesome-repositories.com/f/devops-infrastructure/version-control-management/version-control/git-based.md) — Manages technical documentation and wiki pages using Git-based version control to track changes and peer reviews.
- [Declarative Infrastructure Provisioning](https://awesome-repositories.com/f/devops-infrastructure/cloud-infrastructure-deployment/managed-infrastructure-deployment/infrastructure-deployment-provisioning/declarative-infrastructure-provisioning.md) — Defines hardware and network settings for documentation hosting infrastructure using automated declarative scripts. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/recipes/deploy-docfx-azure-website/))
- [Static Site Deployments](https://awesome-repositories.com/f/devops-infrastructure/deployment-management-strategies/static-site-deployments.md) — Provides an automated pipeline for building static websites and pushing output to hosting providers. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/recipes/using-docfx-and-tools/))

### Education & Learning Resources

- [Implementation Frameworks](https://awesome-repositories.com/f/education-learning-resources/technical-domain-education/computer-science-education/software-engineering-fundamentals/implementation-frameworks.md) — Defines a framework for implementing core requirements for accessibility, security, and continuous delivery. ([source](https://cdn.jsdelivr.net/gh/microsoft/code-with-engineering-playbook@main/README.md))

### Programming Languages & Runtimes

- [Interface Modeling Languages](https://awesome-repositories.com/f/programming-languages-runtimes/specification-languages/interface-modeling-languages.md) — Defines service interfaces using a shared modeling language to automate client library and documentation generation.

### Part of an Awesome List

- [Markdown Formatting](https://awesome-repositories.com/f/awesome-lists/devtools/linting-and-formatting/markdown-formatting.md) — Enforces consistent formatting and style rules across markdown documents using static analysis tools. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/recipes/using-docfx-and-tools/))
- [Bug Tracking Systems](https://awesome-repositories.com/f/awesome-lists/productivity/bug-tracking-systems.md) — Provides a standardized process for capturing and managing software defects with reproduction steps and severity levels. ([source](https://microsoft.github.io/code-with-engineering-playbook/documentation/guidance/work-items/))

### Testing & Quality Assurance

- [Pre-Commit Quality Checks](https://awesome-repositories.com/f/testing-quality-assurance/testing-best-practices-methodologies/quality-assurance-practices/pre-commit-quality-checks.md) — Integrates automated linting, link validation, and grammar checks as pre-commit quality guardrails.