2.4 Project Documentation: Wikis, Mermaid Diagrams & Release Notes

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

1. 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.
2. 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

[!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

1. Flowcharts (graph TD / graph LR): Top-down or left-to-right process workflows.
2. Sequence Diagrams (sequenceDiagram): Synchronous/asynchronous service interactions.
3. Git Graphs (gitGraph): Branching strategies, release tags, and merge patterns.
4. 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.

1. 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
   

2. 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.
3. 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:

$\text{Format: } <\text{type}>[(<\text{optional scope}>)]: <\text{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

1. 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.
2. 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.