Design and implement processes and communications
Collaboration and Documentation
ImportantKeep project, release, and API documentation current and route tool events into collaboration channels through secure, scoped integrations.
Aligned to AZ-400 skills measured as of July 27, 2026; guide and product behavior verified September 25, 2026.
Why this matters
Documentation and chat integrations reduce delay only when generated evidence is trustworthy, events are scoped, and ownership survives staff or tool changes.
Must Know
- Store project documentation and diagrams as versioned Markdown where changes can be reviewed; use supported Mermaid syntax for diagrams.
- Release notes should be derived from curated pull-request or change metadata, not raw commit text with no audience or category discipline.
- API documentation should be generated from a versioned contract such as OpenAPI and published with the related release.
- Webhooks push selected events to a receiver; validate signatures, acknowledge quickly, tolerate retries, and make processing idempotent.
- Azure Boards and GitHub integration uses repository connections and AB# references to link and transition work.
- Microsoft Teams integrations should subscribe the right team or channel to actionable repository, work-item, build, or release events.
Compare and Distinguish
- A webhook is event delivery; polling asks repeatedly for state; a Teams subscription is a collaboration presentation of selected events.
- A project wiki explains enduring design; release notes explain change; API documentation defines an interface.
Scenario examples
- Scenario: Release notes contain internal noise. Think: curate pull-request labels and audience categories before generation.
- Scenario: A webhook delivers duplicates. Think: verify signature and process idempotently using a delivery identifier.
Exam traps
- Auto-generating from inconsistent commit messages automates inconsistency.
- A webhook secret in source control defeats payload verification.
- Sending every pipeline event to Teams makes failure alerts easier to miss.
Key takeaways
- Version documentation near the source it describes.
- Generate from structured metadata and retain human ownership.
- Treat integrations as production systems with authentication, retries, and scope.
How it works
- Version-controlled documentation changes through the same review and history mechanisms as source, while publishing creates a consumer-facing rendition.
- Event integrations deliver a signed occurrence to a receiver that validates, deduplicates, routes, and records the resulting action.
Objects and administrative surfaces
- Azure DevOps project wikis, Markdown renderer, release pipelines, service hooks, Boards connections, and Teams app.
- GitHub repository documentation, Releases, webhooks, Apps, Actions, and Teams integration.
When to use it
- Use a webhook when an external system needs prompt machine-to-machine action on a specific platform event.
Security and governance implications
- Keep webhook secrets and chat credentials outside documentation and pipeline logs, and grant integrations only required repository events.
Troubleshooting signals
- For missed webhook actions, inspect event selection, delivery status, signature validation, receiver timeout, and duplicate handling in order.
More detail
- Use structured pull-request or commit metadata to generate curated release notes instead of publishing an unfiltered Git log.
- Validate webhook signatures, acknowledge quickly, and make receivers idempotent because delivery can be retried.
- Keep API documentation versioned with the release whose behavior it specifies.
Ready for the quiz?
- What makes generated release notes useful to an external audience?
- How should a webhook receiver handle a retried delivery?
- When is a Teams integration preferable to a custom webhook?
Related objectives
- D1.3.S1 — Document a project by configuring wikis and process diagrams, including Markdown and Mermaid syntax
- D1.3.S2 — Configure release documentation, including release notes and API documentation
- D1.3.S3 — Automate creation of documentation from Git history
- D1.3.S4 — Configure integration by using webhooks
- D1.3.S5 — Configure integration between Azure Boards and GitHub repositories
- D1.3.S6 — Configure integration between GitHub or Azure DevOps and Microsoft Teams