Génération de documentation à partir du code d’infrastructure

Le code d’infrastructure est sous-documenté. Un modèle Bicep peut déployer correctement une architecture complexe multiniveau. Mais si personne n’a documenté ce qu’il déploie, pourquoi chaque ressource existe ou ce que contrôlent les paramètres, le modèle devient un savoir tribal. Seule la personne qui l’a écrite peut la changer en toute sécurité.

Cet écart existe, car la documentation est fastidieuse à écrire et facile à ignorer. Après avoir terminé et validé un modèle de Bicep de 400 lignes, l’écriture d’une description d’architecture correspondante ressemble à un projet distinct.

GitHub Copilot modifie cette équation. À partir d’un modèle, Copilot peut générer une première ébauche de documentation en quelques secondes. Le travail de l’ingénieur passe de l’écriture de la documentation à l’examen et à l’affinement. La documentation cesse d’être facultative et commence à faire partie du flux de travail normal.

Génération de descriptions d’architecture en langage brut

La documentation la plus immédiate nécessaire est une explication lisible par l’homme de ce qu’un modèle déploie. Ce niveau de documentation est ce qu’un responsable de projet, un réviseur de sécurité ou un nouveau membre de l’équipe a besoin avant de pouvoir comprendre ou travailler avec l’infrastructure.

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]

L’instruction de structure est importante. Sans cela, Copilot produit une liste plate de ressources plutôt qu'une explication qui transmet l'intention de l'architecture.

Exemple de structure de sortie

Pour un modèle de réseau hub-spoke, une explication bien structurée peut ressembler à ceci :

## 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

Génération de la documentation de référence des paramètres

Les modèles avec de nombreux paramètres sont difficiles à utiliser sans documentation. Une table de référence de paramètre indique aux utilisateurs ce que fait chaque paramètre, quelles valeurs sont valides et quelles sont les valeurs par défaut.

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 génère cette table avec précision, car elle lit les décorateurs @description(), @allowed() et @minLength() directement à partir du modèle. Si votre modèle n’a pas de décorateurs, Copilot déduit les descriptions des noms de paramètres. C’est une autre raison d’utiliser des noms de paramètres descriptifs lors de la génération de modèles.

Génération de références de sorties

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.

Cet exemple est utile pour les sorties de module consommées par d’autres modèles. La documentation de sortie indique à l’appelant ce qu’il reçoit et dans quel format.

Création de diagrammes d’architecture avec Mermaid

Mermaid est un langage de diagramme basé sur du texte pris en charge en mode natif dans GitHub Markdown, Azure DevOps Wiki et VS Code. Il affiche des diagrammes à partir de texte brut. Cela signifie que les diagrammes peuvent se trouver dans le même référentiel que le code d’infrastructure, versionné et mis à jour en même temps que les modèles.

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.

Les diagrammes Mermaid ne sont pas toujours parfaits au pixel près dès la première génération. Demander à Copilot pour ajuster la disposition, ajouter ou supprimer des composants, ou modifier le type de diagramme en fonction de ce qui s’affiche le mieux.

Validation du diagramme

Affichez un aperçu du diagramme dans VS Code à l’aide de l’aperçu Markdown (Ctrl+Shift+V). Si GitHub restitue Mermaid dans le fichier README de votre référentiel, envoyez (push) le fichier et vérifiez la sortie affichée. le renderer de GitHub a un comportement légèrement différent de vs Code.

Si le diagramme est trop complexe à afficher correctement, demandez Copilot simplifier :

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.

Génération de résumés des modifications

Lorsque l’infrastructure change, quelqu’un doit examiner ce qui a changé. Les descriptions de pull requests telles que « modèle Bicep mis à jour » n’apportent aucune information utile au relecteur. Copilot pouvez générer des résumés de modifications significatifs en comparant deux versions d’un modèle.

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]

Ce résumé des modifications est immédiatement utile en tant que description de pull request, communication à destination des parties prenantes ou section d’un runbook de déploiement.

Exemple de sortie du récapitulatif des modifications

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

Conservation de la documentation synchronisée

La défaillance la plus courante de la documentation est son obsolescence. Un document écrit lorsque le modèle était la version 1 devient trompeur par la version 5.

Plusieurs pratiques permettent de maintenir la précision au fil du temps.

Générez la documentation lors du processus de PR. Ajoutez une étape à votre pipeline CI qui signale la PR pour une révision de la documentation lorsque le modèle change de manière significative.

Utilisez les décorateurs @description() comme source de vérité. La documentation incorporée dans le modèle via des décorateurs est toujours synchronisée avec le code, car elle se trouve dans le même fichier. La documentation externe au format Markdown peut devenir obsolète.

Générez de la documentation pour chaque version majeure. Utilisez l’invite de résumé des modifications après chaque fusion significative vers la branche principale. Validez la documentation mise à jour dans la même pull request que la modification du modèle.

Instruction de mise à jour du README :

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