Study guide
2.4 Project Documentation: Wikis, Mermaid Diagrams & Release Notes
Microsoft Certified: Azure DevOps Engineer Expert AZ-400
Track your progress as you read
Finished sections get a check mark.
1 Chapter 1: Flow of Work, Traceability & Work Tracking
1.1 Flow of Work, GitHub Flow & Feedback Cycles 1.2 Work Tracking with Azure Boards & GitHub Projects 1.3 End-to-End DevOps Traceability & Quality Tracking
2 Chapter 2: DevOps Metrics, Dashboards & Team Collaboration
2.1 DORA Metrics, Flow Metrics & Dashboard Design 2.2 Lifecycle Metrics Across the Six DevOps Phases 2.3 Work Item Queries, WIQL Charts & Analytics 2.4 Project Documentation: Wikis, Mermaid Diagrams & Release Notes 2.5 Webhooks, Service Hooks & Microsoft Teams ChatOps
3 Chapter 3: Git Branching Strategies & Pull Request Workflows
3.1 Git Branching Models & Strategy Design 3.2 Pull Request Workflows & Merge Strategies 3.3 Branch Policies, Quality Gates & Compliance Restrictions
4 Chapter 4: Repository Management, Optimization & Git Data Operations
4.1 Git LFS Architecture & .gitattributes Tracking 4.2 LFS History Migration, git-fat & File Locking 4.3 Git Repository Scaling, Scalar & Monorepo Governance 4.4 Repository Permissions & Git Tag Governance 4.5 Git Data Recovery & Sensitive-Data Scrubbing
5 Chapter 5: Package Management & Dependency Versioning
5.1 Selecting Package Tools: Azure Artifacts vs. GitHub Packages 5.2 Feed Scoping, Upstream Sources & Pipeline Authentication 5.3 Package Views, Immutability & Quality Promotion 5.4 Dependency Versioning: SemVer, CalVer & Automated Versioning 5.5 Pipeline Artifact Versioning & Artifact Storage Strategy
6 Chapter 6: Pipeline Infrastructure, Agents & Integration
6.1 Selecting a CI/CD Solution: Azure Pipelines vs. GitHub Actions 6.2 GitHub-Azure Pipelines Integration & Hybrid Migration 6.3 Hosted vs. Self-Hosted Agents & Runners 6.4 VMSS Elastic Pools, Container Jobs & Agent Governance 6.5 Pipeline Triggers, Filters & Concurrency Management
7 Chapter 7: YAML Pipeline Architecture & Reusable Elements
7.1 YAML Pipeline Anatomy: Stages, Jobs, Steps & Workspaces 7.2 Job Execution Order: DAG Dependencies, Parallelism & Conditions 7.3 Reusable Elements: Templates, Parameters & Variables 7.4 Variable Groups, Secret Variables & Key Vault Linking 7.5 YAML Environments, Checks & Deployment Approvals
8 Chapter 8: Testing Strategy, Quality Gates & Code Coverage
8.1 Test Strategy Design: Local, Unit & Integration Testing 8.2 Load, Stress & Performance Testing in Pipelines 8.3 Test Execution Tasks, Agents & Results Integration 8.4 Code Coverage Analysis & SonarQube Integration 8.5 Quality Gates, Release Gates & Governance Checks
9 Chapter 9: Modern Deployment Strategies & Zero-Downtime Delivery
9.1 Progressive Delivery: Blue-Green, Canary & Ring Deployments 9.2 Minimizing Downtime: Deployment Slots & Rolling Updates 9.3 Feature Flags with Azure App Configuration & Feature Manager 9.4 Designing the High-Priority Hotfix Path 9.5 Ordered Dependency Deployments, Resiliency & Rollback
10 Chapter 10: Artifact Deployment & Database DevOps
10.1 Containerized Application Delivery: ACR, AKS & Container Apps 10.2 Binary, Web App, Function & Scripted Deployments 10.3 Database DevOps: State-Based & Migration-Based Strategies
11 Chapter 11: Infrastructure as Code (IaC) & Azure Deployment Environments
11.1 Infrastructure as Code Strategy: Bicep, ARM & Terraform 11.2 Desired State Configuration & Azure Machine Configuration 11.3 Azure Deployment Environments (ADE) & Developer Self-Service
12 Chapter 12: Pipeline Maintenance, Health & Modernization
12.1 Pipeline Health, Flaky Tests & Reliability Engineering 12.2 Pipeline Optimization: Caching, Slicing & Concurrency 12.3 Artifact & Build Retention Governance 12.4 Modernizing CI/CD: Classic to YAML Migration
13 Chapter 13: Authentication, Authorization & Identity Governance
13.1 Microsoft Entra Service Principals & Managed Identities 13.2 Service Connections, Workload Identity & Personal Access Tokens 13.3 Azure DevOps Projects, Teams & Permission Evaluation 13.4 Access Levels, GitHub Roles & Outside Collaborators
14 Chapter 14: Secrets Management, Sensitive Data & DevSecOps Scanning
14.1 Azure Key Vault, Secret Variables & Secretless CI/CD 14.2 Security Scanning Strategy, GHAS & Secret Scanning 14.3 CodeQL SAST in Pipelines and Containers 14.4 Software Supply Chain, Container Scanning & Cloud Defender
15 Chapter 15: Telemetry Collection, Azure Monitor & Alerting
15.1 Azure Monitor Architecture, AMA & Data Collection Rules 15.2 Application Insights & Specialized Azure Monitor Insights 15.3 Alerting Rules, Action Groups & GitHub Repository Insights
16 Chapter 16: Telemetry Analysis, Distributed Tracing & SRE Practices
16.1 Distributed Tracing, Application Map & Exception Triage 16.2 KQL Log Analytics, SRE Observability & Error Budgets
2.4 Project Documentation: Wikis, Mermaid Diagrams & Release Notes
Key Takeaways Explain This Topic AI
A project wiki is a hidden Git repository managed by Azure DevOps; publishing code as wiki serves Markdown straight from a branch of a product repository and inherits its branch policies.
Publish-code-as-wiki is the correct choice when documentation must be reviewed through pull requests and versioned with the code it describes.
Mermaid blocks render flowcharts, sequence diagrams, class diagrams, state diagrams and Gantt charts directly inside wiki pages, keeping architecture diagrams in version control as text.
Conventional Commits (feat, fix, chore, BREAKING CHANGE) are what allow release notes and semantic version bumps to be generated automatically from Git history.
OpenAPI or Swagger specifications published as a pipeline artifact keep API documentation synchronised with the deployed build rather than with a hand-edited page.
Last updated: September 2026
2.4 Project Documentation: Wikis, Mermaid Diagrams & Release Notes
Collaborative engineering in enterprise DevOps environments depends on living documentation, automated release communication, and real-time operational ChatOps. When documentation resides in disconnected silos or release notes are manually assembled, delivery velocity and audit compliance suffer. Azure DevOps provides native mechanisms to maintain documentation as code, embed version-controlled diagrams, automate changelogs, and drive event-driven approvals via Microsoft Teams ChatOps.
Azure DevOps Wikis: Project Wiki vs. Publish Code as Wiki
Azure DevOps provides two distinct architectures for maintaining documentation: Project Wiki and Publish Code as Wiki (Code Wiki) . +-----------------------------------------------------------------------------------------+
- | AZURE DEVOPS WIKI ARCHITECTURES |
- +---------------------------------------------+-------------------------------------------+
- | PROJECT WIKI | PUBLISH CODE AS WIKI |
- +---------------------------------------------+-------------------------------------------+
- | * Provisioned by default in Project | * Published from a Git repo folder (/docs)|
- | * Stored in hidden system Git repository | * Stored alongside application codebase |
- | * Single documentation version | * Supports Git branches and release tags |
- | * Direct edits via Web UI | * Enforces Pull Requests & Branch Policies|
- | * Single wiki per Azure DevOps project | * Multiple code wikis per team project |
- +---------------------------------------------+-------------------------------------------+
- Deep Architectural Comparison
Project Wiki:
Created automatically when you initialize a wiki in Azure DevOps ( Overview > Wiki > Create Project Wiki ).
Backed by a hidden, managed Git repository named <ProjectName>.wiki .
Limitation: Does not support branching or versioning. There is only one live version of the documentation. It cannot be mapped to release versions of your software.
Ideal for general project onboarding, team charters, and high-level stakeholder guidelines.
Publish Code as Wiki (Code-as-Wiki):
Created by selecting Overview > Wiki > Publish code as wiki and pointing to a specific Git repository, branch, and subfolder (e.g., repository ECommerceCore , branch main , folder /docs ).
Branching & Versioning: Because documentation lives in a standard Git repository, you can branch documentation alongside feature code. When releasing software version v2.0 , you can branch or tag the wiki to correspond exactly with v2.0 .
Pull Request Governance: Documentation edits require pull requests, enabling peer reviews, markdown linting pipelines, and automated policy checks before merging.
Multi-Wiki Support: You can publish multiple code wikis within a single Azure DevOps project (e.g., one wiki per microservice repository).
Architectural Decision Matrix
- Feature Project Wiki Publish Code as Wiki
- Underlying Storage Hidden system Git repository Standard project Git repository
- Branching Support No (Single branch only) Yes (Switch branches/tags in UI)
- Pull Request Review Workflow No (Direct edits in Web UI) Yes (Enforces branch policies)
- Release Version Tagging No Yes (Maps to Git release tags)
- Number of Wikis per Project Exactly 1 Unlimited (Multi-repo wikis)
- Folder Sequencing Control Drag-and-drop or .order files .order file in repository folder
- Offline Git Clone Access Cloneable via hidden URL Standard git clone with repo
Tip
The .order File Mechanism: In both wiki types, page order in the navigation sidebar is determined alphabetically by default. To specify custom page ordering, Azure DevOps utilizes a hidden metadata file named .order . The .order file lists file basenames without extensions in the desired vertical order. In a Code Wiki, you can version-control this file directly in Git.
Architecture & Process Diagrams with Mermaid
Azure DevOps Wikis, Markdown files in Azure Repos, and Pull Request descriptions natively support Mermaid.js syntax. This enables Architecture as Code —diagrams live in plain-text markdown, are version-controlled in Git, and render dynamically in the web UI.
Key Supported Diagram Types
Flowcharts ( graph TD / graph LR ): Top-down or left-to-right process workflows.
Sequence Diagrams ( sequenceDiagram ): Synchronous/asynchronous service interactions.
Git Graphs ( gitGraph ): Branching strategies, release tags, and merge patterns.
Class & Entity Relationship Diagrams ( classDiagram / erDiagram ): Data models and component contracts.
- Practical Mermaid Implementation: CI/CD Deployment with Approval Gates ```mermaid
- sequenceDiagram
- autonumber
- actor Dev as Developer
- participant Repo as Azure Repos (main)
- participant Pipe as Azure Pipelines (CI/CD)
- participant Gate as Environment Approval Gate
- participant Lead as Release Approver
- participant Prod as Azure App Service (Prod)
- Dev->>Repo: Merge Pull Request (Commit to main)
- Repo->>Pipe: Webhook Trigger CI Build & Tests
- Pipe->>Pipe: Execute Unit Tests & SAST Scan
- Pipe->>Gate: Trigger Deployment to 'Production' Env
- Gate->>Lead: Post Interactive Card to Microsoft Teams
- Note over Gate,Lead: Pipeline pauses execution
- Lead->>Gate: Click 'Approve' in Teams Actionable Card
- Gate->>Pipe: Approval Token Validated
- Pipe->>Prod: Deploy Artifact via Blue-Green Swap
- Prod-->>Pipe: Health Check HTTP 200 OK
- Pipe-->>Dev: Build Succeeded Notification
- ```
- Automated Release Documentation & API Documentation
- Automated Release Notes Generation
Manual release note assembly is error-prone and causes audit failures in regulated environments. Azure Pipelines automates release documentation by querying associated work items, pull requests, and commit logs.
REST API Data Extraction: During the release pipeline, scripts query the Azure DevOps REST API for all work items linked to the current build: GET https://dev.azure.com/{organization}/{project}/_apis/build/builds/{buildId}/workitems?api-version=7.1
Pipeline Integration: Tasks such as the marketplace Xplat Generate Release Notes or custom PowerShell/Bash tasks extract the work item titles, bug fixes, breaking changes, and contributor lists, compiling them into a formatted RELEASE_NOTES.md file.
Artifact & Wiki Publication: The generated notes are published directly to the GitHub Release , attached to the Azure DevOps Release Run , or committed automatically into the project Wiki via REST API.
OpenAPI / Swagger Documentation Pipelines
For API services, documentation must stay in sync with code contracts:
In the CI build pipeline, a build step executes CLI tools (e.g., dotnet swagger tofile or npx redoc-cli ) to generate the OpenAPI specification ( swagger.json ).
Breaking Change Detection: Tools like openapi-diff compare the newly generated swagger.json against the production OpenAPI spec. If breaking changes (e.g., removed endpoints, altered parameter types) are detected on non-major version branches, the pipeline fails.
Portal Publication: The validated spec is published to the Azure API Management (APIM) developer portal or static documentation hosts (Azure Static Web Apps).
- Documentation from Git History & Conventional Commits
- The Conventional Commits Standard
To automate changelog generation and semantic versioning, organizations enforce Conventional Commits across repository commit messages: Format: < type > [ ( < optional scope > ) ] : < description > \text{Format: } <\text{type}>[(<\text{optional scope}>)]: <\text{description}> Format: < type > [( < optional scope > )] :< description >
Standard Types:
feat : A new feature (corresponds to a Minor version bump in SemVer: 1.1.0 -> 1.2.0 ).
fix : A bug patch (corresponds to a Patch version bump in SemVer: 1.1.0 -> 1.1.1 ).
docs : Documentation changes only.
chore / refactor / perf / test : Maintenance, refactoring, performance improvements, or test suites (no SemVer bump).
Breaking Changes:
Indicated by appending an exclamation mark ! after the type/scope (e.g., feat(api)!: remove v1 endpoints ) or adding a footer BREAKING CHANGE: <explanation> .
Corresponds to a Major version bump in SemVer: 1.1.0 -> 2.0.0 .
Enforcement Strategies
Client-Side Git Hooks: Configured via Husky ( commit-msg hook). Validates message syntax before local commit creation. Note: Client hooks can be bypassed using git commit --no-verify .
Server-Side PR Policies (Azure Repos): The production-grade enforcement tested on AZ-400. In Azure Repos, configure a Build Validation Policy or a Status Check Policy on the main branch. A pipeline step parses the Pull Request title using tools like @commitlint/cli and blocks PR completion if the title violates Conventional Commit specifications.