Topic 1.3 — Collaboration and communication · cram sheet

Wikis

• Publish code as wiki → docs live in the code repo, reviewed in the same PR. Project wiki drifts.
• Azure DevOps wiki renders Mermaid: sequence, flowchart, Gantt, class, state, user journey, pie, requirements, gitgraph, ER, timeline.
• Diagrams as text diff in a PR; exported images do not.

Release documentation

• Generate notes from linked work items (intent), not commit subjects (implementation).
• Generate API reference from source; hand-written goes stale silently.
• Deploy docs with the release so versions match.

Docs from Git history

Enforce the convention in PR validation — unenforced conventions decay and the automation goes silently wrong. Automation gives the what, never the why.

Webhooks (Azure DevOps: service hooks)

• Push, not poll.
• Delivery is at-least-once → receivers must be idempotent.
• The secret signs the payload — verify it, or the endpoint is an open trigger.
• Plan a reconciliation path for missed deliveries.

Boards ↔ GitHub

• Authenticate with the Azure Boards app, not a PAT. A PAT-based connection dies when its owner leaves.
• Repos outside the connection scope never link.

Teams

• Post what needs a decision or action.
• Approving from Teams is a surface; the control is still the environment check.