Generowanie dokumentacji na podstawie kodu infrastruktury

Kod infrastruktury jest notorycznie słabo udokumentowany. Szablon Bicep może poprawnie wdrożyć złożoną architekturę wielowarstwową. Ale jeśli nikt nie udokumentował, co wdraża, dlaczego istnieje każdy zasób ani za co odpowiadają parametry, szablon staje się wiedzą dostępną tylko wtajemniczonym. Tylko osoba, która ją napisała, może ją bezpiecznie zmienić.

Ta luka istnieje, ponieważ dokumentacja jest żmudna do pisania i łatwego pomijania. Po ukończeniu i zweryfikowaniu szablonu Bicep liczącego 400 wierszy napisanie odpowiadającego mu opisu architektury wydaje się osobnym projektem.

GitHub Copilot zmienia to równanie. Biorąc pod uwagę szablon, Copilot może wygenerować pierwszą wersję roboczą dokumentacji w ciągu kilku sekund. Rola inżyniera przesuwa się z pisania dokumentacji na jej przeglądanie i dopracowywanie. Dokumentacja przestaje być opcjonalna i zaczyna być częścią normalnego przepływu pracy.

Generowanie opisów architektury w języku prostym

Najbardziej bezpośrednią potrzebą dokumentacji jest czytelne dla człowieka wyjaśnienie, co wdraża szablon. Ten poziom dokumentacji jest wymagany przez menedżera projektu, recenzenta zabezpieczeń lub nowego członka zespołu, zanim będzie mógł zrozumieć infrastrukturę lub pracować z tą infrastrukturą.

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]

Instrukcja struktury jest ważna. Bez niego Copilot tworzy płaską listę zasobów, a nie wyjaśnienie, które przekazuje intencję architektury.

Przykładowa struktura danych wyjściowych

W przypadku szablonu sieci typu hub-and-spoke dobrze uporządkowane wyjaśnienie może wyglądać następująco:

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

Generowanie dokumentacji referencyjnej parametrów

Szablony z wieloma parametrami są trudne do użycia bez dokumentacji. Tabela referencyjna parametrów informuje użytkowników o tym, co robi każdy parametr, jakie wartości są prawidłowe i jakie są wartości domyślne.

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 generuje tę tabelę poprawnie, ponieważ odczytuje dekoratory @description(), @allowed() i @minLength() bezpośrednio z szablonu. Jeśli szablon nie ma dekoratorów, Copilot wywnioskuje opisy z nazw parametrów. Jest to kolejny powód używania opisowych nazw parametrów podczas generowania szablonów.

Generowanie odwołania do danych wyjściowych

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.

Ten przykład jest przydatny w przypadku danych wyjściowych modułu używanych przez inne szablony. Dokumentacja danych wyjściowych informuje wywołującego, co otrzymuje i w jakim formacie są te dane.

Tworzenie diagramów architektury za pomocą Mermaid

Mermaid to tekstowy język do tworzenia diagramów, obsługiwany natywnie w GitHub Markdown, Azure DevOps Wiki i VS Code. Renderuje diagramy z zwykłego tekstu. Oznacza to, że diagramy mogą znajdować się w tym samym repozytorium co kod infrastruktury, wersjonowany i aktualizowany wraz z szablonami.

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.

Diagramy Mermaid nie zawsze są idealne co do piksela przy pierwszym wygenerowaniu. Poproś Copilota, aby dostosował układ, dodał lub usunął elementy albo zmienił typ diagramu na podstawie tego, co wygląda najlepiej.

Walidacja diagramu

Wyświetl podgląd diagramu w programie VS Code przy użyciu wersji zapoznawczej języka Markdown (Ctrl+Shift+V). Jeśli GitHub renderuje Mermaid w pliku README repozytorium, wypchnij plik i sprawdź tam wyrenderowany wynik. GitHub renderator ma nieco inne zachowanie niż program VS Code.

Jeśli diagram jest zbyt złożony, aby dało się go czytelnie wyrenderować, poproś Copilota o jego uproszczenie:

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.

Generowanie podsumowań zmian

Gdy zmienia się infrastruktura, ktoś musi przejrzeć zmiany. Opisy pull requestów, takie jak „zaktualizowany szablon Bicep”, nie dostarczają recenzentowi żadnych przydatnych informacji. Copilot może generować znaczące podsumowania zmian, porównując dwie wersje szablonu.

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]

To podsumowanie zmian jest od razu przydatne jako opis pull requestu, komunikat dla interesariuszy lub sekcja w runbooku wdrożeniowym.

Przykładowy wynik podsumowania zmian

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

Przechowywanie dokumentacji w synchronizacji

Najczęstszym niepowodzeniem dokumentacji jest nieaktualność. Dokument napisany, gdy szablon miał wersję 1, staje się mylący w wersji 5.

Kilka praktyk pomaga utrzymać dokładność na przestrzeni czasu.

Generuj dokumentację w ramach procesu PR. Dodaj krok do potoku CI, który oznacza PR do przeglądu pod kątem dokumentacji, gdy szablon znacząco się zmieni.

Użyj @description() dekoratorów jako źródła prawdy. Dokumentacja osadzona w szablonie za pośrednictwem dekoratorów jest zawsze zsynchronizowana z kodem, ponieważ znajduje się w tym samym pliku. Zewnętrzna dokumentacja w formacie Markdown może z czasem się dezaktualizować.

Generuj dokumentację dla każdego głównego wydania. Użyj monitu podsumowania zmian po każdej znaczącej scalaniu do głównej. Zacommituj zaktualizowaną dokumentację w tym samym PR co zmianę w szablonie.

Monit dotyczący aktualizacji 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