Dokumentationsgenerering ud fra infrastrukturkode

Infrastrukturlovgivning er notorisk underdokumenteret. En Bicep-skabelon kan korrekt implementere en kompleks, flerlags arkitektur. Men hvis ingen dokumenterede, hvad den deployerer, hvorfor hver ressource eksisterer, eller hvad parametrene styrer, bliver skabelonen stammeviden. Kun den person, der skrev den, kan sikkert ændre den.

Dette hul eksisterer, fordi dokumentation er besværlig at skrive og let at springe over. Efter at have færdiggjort og valideret en 400-linjers Bicep-skabelon, føles det som et separat projekt at skrive en tilsvarende arkitekturbeskrivelse.

GitHub Copilot ændrer denne ligning. Givet en skabelon kan Copilot generere et første udkast af dokumentationen på få sekunder. Ingeniørens job skifter fra at skrive dokumentation til at gennemgå og forfine den. Dokumentation holder op med at være valgfri og bliver en del af den normale arbejdsgang.

Generering af enkle arkitekturbeskrivelser

Det mest presserende dokumentationsbehov er en menneskelig læsbar forklaring på, hvad en skabelon implementerer. Dette niveau af dokumentation er det, en projektleder, en sikkerhedsgennemgang eller et nyt teammedlem har brug for, før de kan forstå eller arbejde med infrastrukturen.

Explain what this Bicep template deploys in plain language.
Structure your explanation as follows:
1. A one-paragraph summary of the overall architecture
2. A section for each major resource group or logical component,
   describing what it does and why it exists
3. A description of how the components connect to each other
4. Any security controls that are configured

Use language that a technical project manager could understand.
Avoid Bicep-specific syntax in the explanation.

[paste template here]

Strukturinstruktionen er vigtig. Uden den producerer Copilot en flad liste over ressourcer i stedet for en forklaring, der formidler arkitekturens hensigt.

Eksempel på outputstruktur

For en hub-eeger netværksskabelon kan en velstruktureret forklaring se sådan ud:

## Architecture Overview

This template deploys a hub-and-spoke network topology for Azure, a standard
pattern for enterprise environments that need centralized security controls
alongside segmented workload networks.

## Hub Network
The hub virtual network (10.0.0.0/16) is the central connection point for all
network traffic. It hosts the Azure Firewall, which inspects and filters all
traffic entering and leaving the environment. It also contains an Azure Bastion
host, which provides secure browser-based access to virtual machines without
exposing RDP or SSH ports to the internet.

## Spoke Network
The spoke virtual network (10.1.0.0/16) is where application workloads run.
It connects to the hub through VNet peering, a low-latency, private connection
within the Azure backbone. Traffic from the spoke to the internet is routed
through the hub firewall, ensuring all outbound connections are inspected.

## Observability
A Log Analytics workspace collects diagnostic logs from the Azure Firewall.
This enables security monitoring, threat detection, and compliance auditing
from a single location.

## Security Controls
- All internet-bound traffic from workloads is inspected by Azure Firewall
- No management ports (SSH, RDP) are exposed directly to the internet
- Network access to VMs is restricted to Azure Bastion sessions only

Generering af parameterreferencedokumentation

Skabeloner med mange parametre er svære at bruge uden dokumentation. En parameterreferencetabel fortæller brugerne, hvad hver parameter gør, hvilke værdier der er gyldige, og hvad standardværdierne er.

Generate a markdown parameter reference table for this Bicep template.
Include these columns:
| Parameter | Type | Default | Allowed Values | Description |

Cover all parameters. For parameters with @allowed() decorators,
list the allowed values. For parameters with no default, mark the
Default column as "Required". Write descriptions in plain language,
not a repeat of the parameter name.

Copilot genererer denne tabel nøjagtigt, fordi den læser @description(), @allowed() og @minLength() dekoratørerne direkte fra skabelonen. Hvis din skabelon mangler dekoratører, udleder Copilot beskrivelser ud fra parameternavnene. Hvilket er en anden grund til at bruge beskrivende parameternavne, når man genererer skabeloner.

Reference til generering af outputs

Add a second table below the parameters table documenting all outputs
from this template. Include: Output Name | Type | Description.
Describe what each output contains and when you would use it.

Dette eksempel er nyttigt for moduloutput, der forbruges af andre skabeloner. Outputdokumentationen fortæller opkalderen, hvad de modtager, og hvilket format det er i.

Oprettelse af arkitekturdiagrammer med Mermaid

Mermaid er et tekstbaseret diagramsprog, der understøttes native i GitHub Markdown, Azure DevOps Wiki og VS Code. Den gengiver diagrammer fra almindelig tekst. Det betyder, at diagrammer kan ligge i det samme repository som infrastrukturkoden, versioneret og opdateret sammen med skabelonerne.

Represent the network topology deployed by this Bicep template as a Mermaid diagram.
Use flowchart LR (left to right) direction.
Show:
- Each VNet as a subgraph
- Subnets as nodes inside their VNet subgraph
- Resources (Firewall, Bastion, VMs) as nodes in the appropriate subnet
- VNet peering as a double-headed arrow between VNets
- The Log Analytics workspace outside the VNets, with a log collection arrow
  from the Firewall
- Use descriptive labels on each node showing the resource name and type

Wrap the Mermaid code in a markdown code block with the mermaid language tag.

Havfruediagrammer er ikke altid pixel-perfekte på første generation. Spørg Copilot om at justere layoutet, tilføje eller fjerne komponenter, eller ændre diagramtypen baseret på, hvad der renderes bedst.

Diagramvalidering

Forhåndsvis diagrammet i VS Code ved hjælp af Markdown Preview (Ctrl+Shift+V). Hvis GitHub renderer Mermaid i dit repositorys README, så push filen og tjek det renderede output der. GitHub's renderer har en lidt anderledes adfærd end VS Codes.

Hvis diagrammet er for komplekst til at gengives rent, bed Copilot om at forenkle:

Simplify this Mermaid diagram to show only the major components and their
connections. Remove subnet-level detail and focus on the resource relationships
at the VNet level.

Generering af ændringsresuméer

Når infrastrukturen ændrer sig, skal nogen gennemgå, hvad der er ændret. Pull request-beskrivelser som "opdateret Bicep-skabelon" giver ingen brugbar information til en reviewer. Copilot kan generere meningsfulde ændringsoversigter ved at sammenligne to versioner af en skabelon.

Compare these two Bicep templates (v1 and v2) and generate a change summary
in markdown format.

For each change, include:
- What changed (resource added, modified, or removed)
- Why it likely changed (e.g., added for security, added for observability,
  fixed a misconfiguration)
- Impact on existing deployments (e.g., requires redeployment, causes downtime,
  is additive only)

Group changes by category: Security, Observability, Networking, Compute, Cost.

--- v1 template ---
[paste old template]

--- v2 template ---
[paste new template]

Dette ændringsresumé er straks nyttigt som en pull request-beskrivelse, en kommunikation til interessenter eller et afsnit i en deployment-runbook.

Eksempel på ændringsresume-output

## Infrastructure Change Summary — v1 to v2

### Security
- **Added:** AzureFirewallSubnet resized from /27 to /26
  - *Why:* Azure Firewall requires a minimum /26 subnet. The /27 caused deployment failures.
  - *Impact:* Requires redeployment of the hub VNet. Existing peering will need to be re-established.

- **Added:** CostCenter tag on all resources
  - *Why:* Azure Policy requires a CostCenter tag. Missing tag caused policy denial.
  - *Impact:* Additive only. No resource changes.

### Observability
- **Added:** Azure Bastion host in AzureBastionSubnet
  - *Why:* Provides browser-based secure access to VMs without exposing management ports.
  - *Impact:* Additive. New resource. Costs approximately $140/month per Bastion instance.

- **Added:** Log Analytics Workspace and Firewall diagnostic settings
  - *Why:* Required for security monitoring and compliance auditing.
  - *Impact:* Additive. Data ingestion costs depend on log volume.

Holder dokumentationen synkroniseret

Den mest almindelige dokumentationsfejl er stagnation. Et dokument skrevet da skabelonen var version 1, bliver vildledende ved version 5.

Flere praksisser hjælper med at opretholde nøjagtigheden over tid.

Generer dokumentation som en del af PR-processen. Tilføj et trin til din CI-pipeline, der markerer PR til dokumentationsgennemgang, når skabelonen ændrer sig væsentligt.

Brug @description() dekoratører som sandhedens kilde. Dokumentation, der er indlejret i skabelonen via dekoratorer, er altid synkroniseret med koden, fordi den ligger i den samme fil. Ekstern markdown-dokumentation kan drive.

Generer dokumentation for hver større udgivelse. Brug ændringsoversigtsprompten efter hver væsentlig sammenfletning til main. Commit den opdaterede dokumentation i samme PR som skabelonændringen.

Prompt til en README-opdatering:

The following changes were made to our infrastructure template in this release:
[paste change summary]

Update the Infrastructure README to reflect these changes. Specifically:
- Update the Architecture Overview section to mention Azure Bastion
- Add the new CostCenter parameter to the parameter reference table
- Update the "Resources Deployed" list