Docs
Artificial Intelligence
Documenti tecnici con AI

Documenti tecnici con AI generativa 🤖

Perché usare l’AI per la documentazione tecnica? 🤔

Scrivere documentazione tecnica è un po’ come andare dal dentista: tutti sanno che è importante, ma nessuno lo fa volentieri. L’AI generativa, però, può trasformare questa esperienza in qualcosa di (quasi) piacevole! Grazie ai modelli di linguaggio, oggi possiamo generare documenti chiari, coerenti e persino personalizzati, partendo da semplici prompt e template.

  • Risparmi tempo (e mal di testa)
  • Riduci errori e dimenticanze
  • Standardizzi lo stile
  • Faciliti la collaborazione

⚠️ Nota importante: Ricorda sempre di ricontrollare i documenti generati dall’AI: anche i modelli più avanzati possono commettere errori, omissioni o fraintendimenti. Ogni richiesta effettuata con lo stesso prompt può produrre risultati diversi: verifica sempre la correttezza, la coerenza e l’aderenza agli standard del tuo team prima di utilizzare o condividere la documentazione.

I vantaggi dei template Markdown 📋

Il Markdown è la lingua franca della documentazione tecnica: semplice, leggibile e perfetto per essere processato sia dagli umani che dalle macchine (e dagli sviluppatori che non amano i fronzoli). Usare template Markdown con l’AI significa:

  • Strutturare le informazioni in modo chiaro
  • Ridurre la sindrome del “romanzo fantasy”
  • Favorire la riusabilità e la coerenza tra i documenti
  • Essere facilmente interpretato dalle principali piattaforme SaaS di gestione documentale
  • Consentire il versionamento tramite sistemi di controllo come Git

Come funziona la generazione assistita 🪄

  1. Definisci i punti chiave: cosa vuoi comunicare? Quali sono le informazioni essenziali?
  2. Scegli (o crea) un template: meglio se già collaudato dal team.
  3. Prompta l’AI: fornisci i punti chiave e chiedi di compilare il template.
  4. Rivedi e personalizza: l’AI è brava, ma tu sei meglio! Aggiungi dettagli, correggi imprecisioni e adatta il tono.

Pro tip: più dettagli fornisci nel prompt, più la documentazione sarà precisa e utile. L’AI non legge nel pensiero (ancora).

Esempio pratico: RFC generata con AI 🚀

Ecco un esempio di prompt e di risultato ottenibile con un template Markdown per RFC (Request for Comments):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

Genera un documento RFC (Request for Comments) in stile tecnico e chiaro, utilizzando il seguente template Markdown.
La RFC deve essere concisa ma formale, adatta a documentare proposte tecniche interne a un team di sviluppo.
Inserisci i contenuti nei campi appropriati in base ai punti chiave forniti.

<template>
# RFC: <Titolo della proposta>

- **ID**: RFC-<numero o abbreviazione>
- **Autore/i**: <Nome/i>
- **Data**: <YYYY-MM-DD>
- **Stato**: Proposta / Approvata / Rifiutata / In Lavorazione
- **Versione**: 1.0

## Sommario

<!-- Breve descrizione della proposta -->

## Motivazione

<!-- Perché è necessaria questa proposta? Quali problemi risolve o migliora? -->

## Obiettivi

<!-- Elenco puntato degli obiettivi principali della proposta -->

## Soluzione Proposta

<!-- Descrizione tecnica della soluzione suggerita, con dettagli sufficienti per la discussione e implementazione -->

## Alternative Considerate

<!-- Altre soluzioni valutate e perché sono state scartate -->

## Impatto

<!-- Impatti attesi sul sistema, sui team, sulla sicurezza o su altri ambiti -->

## Implementazione

<!-- Panoramica del piano di implementazione: step tecnici, rollout, dipendenze -->

## Note Finali

<!-- Considerazioni aggiuntive, riferimenti a documentazione, standard correlati, ecc. -->
</template>

Punti chiave:

Unendolo con dei punti chiave come nell’esempio che segue:

1
2
3
4
5
6
7
8

- Introdurre comunicazione event-driven tra microservizi
- Utilizzare NATS come message broker per pub/sub e request/reply
- Obiettivo: ridurre accoppiamento tra servizi e migliorare scalabilità
- Servizi coinvolti: User Service, Notification Service, Billing Service
- NATS scelto per leggerezza, performance e facilità d’uso
- Valutata alternativa Kafka, scartata per complessità non necessaria
- Sicurezza con mTLS, tracciamento eventi con OpenTelemetry
- Rollout graduale: affiancamento a REST, poi migrazione progressiva

Utilizzando in ChatGPT il prompt con template ed i punti chiave si può ottenere un documento come quello che segue:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

# RFC: Introduzione di Comunicazione Event-Driven tra Microservizi con NATS

- **ID**: RFC-EVENTDRIVEN-NATS
- **Autore/i**: Team Architettura
- **Data**: 2025-05-03
- **Stato**: Proposta
- **Versione**: 1.0

## Sommario

Questa RFC propone l'adozione di un'architettura event-driven per la comunicazione asincrona tra microservizi chiave, utilizzando NATS come message broker per i pattern pub/sub e request/reply. L'obiettivo è migliorare la scalabilità e ridurre l'accoppiamento tra componenti del sistema.

## Motivazione

L'attuale comunicazione sincrona basata su REST introduce accoppiamento stretto tra microservizi, rendendo difficile la scalabilità orizzontale e la resilienza. Con l'aumento delle interazioni tra i servizi User, Notification e Billing, diventa necessario adottare una soluzione che favorisca l'asincronia, la disaccoppiamento e la gestione efficiente degli eventi.

## Obiettivi

- Introdurre comunicazione event-driven tra microservizi selezionati
- Ridurre l'accoppiamento diretto tra servizi
- Migliorare la scalabilità e la resilienza dell'architettura
- Utilizzare NATS come sistema di messaggistica leggero e performante
- Integrare sicurezza tramite mTLS
- Abilitare il tracciamento distribuito tramite OpenTelemetry
- Garantire una transizione graduale e controllata

## Soluzione Proposta

Si propone l'adozione di **NATS** come message broker per implementare la comunicazione event-driven tra i seguenti microservizi:

- **User Service**: emette eventi su creazione/modifica utente
- **Notification Service**: si sottoscrive a eventi utente per inviare notifiche
- **Billing Service**: emette ed elabora eventi relativi a transazioni

### Pattern Supportati

- **Pub/Sub**: per notifiche e aggiornamenti asincroni
- **Request/Reply**: per operazioni che richiedono risposta puntuale, mantenendo l'opzione sincrona tramite messaggistica

### Sicurezza

- Comunicazione cifrata con **mutual TLS (mTLS)**
- Autenticazione dei servizi tramite certificati client

### Observability

- Integrazione con **OpenTelemetry** per tracciamento distribuito di eventi e performance

### Topic Naming

Topic organizzati per dominio funzionale, es: `user.created`, `billing.invoice.issued`, `notification.sent`.

## Alternative Considerate

- **Apache Kafka**: scartato per complessità operativa e sovraccarico infrastrutturale rispetto ai requisiti attuali
- **Google Pub/Sub**: valutato ma non preferito per la necessità di semplicità e deployment locale in ambienti on-prem o ibridi

## Impatto

- **Sistema**: aumento della disaccoppiamento tra microservizi, maggiore resilienza a fault
- **Team**: necessaria formazione minima su NATS e principi event-driven
- **Sicurezza**: rafforzata con mTLS tra componenti
- **Observability**: migliorata tramite OpenTelemetry e tracing distribuito

## Implementazione

1. **Fase 1**: Setup ambiente NATS in staging con certificati mTLS
2. **Fase 2**: Abilitazione in parallelo a REST, con doppia emissione eventi (sidecar o logica interna)
3. **Fase 3**: Verifica della ricezione corretta da Notification e Billing
4. **Fase 4**: Graduale dismissione delle chiamate REST nei percorsi consolidati
5. **Fase 5**: Refactoring progressivo degli altri microservizi secondo modello event-driven

## Note Finali

- Documentazione tecnica NATS: https://docs.nats.io
- Specifiche OpenTelemetry: https://opentelemetry.io
- Il rollout avverrà inizialmente in ambienti non critici, per poi estendersi in produzione previa validazione dei risultati.

Dal template RFC all’ADR: automatizza le decisioni architetturali 🏗️

Hai prodotto una RFC dettagliata con l’AI, ma ora serve una decisione architetturale chiara e riassunta? Nessun problema: puoi chiedere all’AI di trasformare la RFC in un ADR (Architectural Decision Record) usando un template dedicato. Così ottieni una traccia sintetica, facilmente consultabile e pronta per essere condivisa con il team (o dimenticata in una cartella, come da tradizione).

Il processo è semplice: fornisci la RFC all’AI, chiedi di estrarre i punti chiave e di adattarli al formato ADR. In questo modo, la storia delle decisioni architetturali resta documentata e accessibile, senza dover riscrivere tutto da zero.

L’AI può generare l’ADR partendo dalla RFC, estraendo i punti chiave e adattando il formato. Indica la RFC di origine tra i tag <rfc></rfc> e aggiungi un riassunto della decisione nei punti chiave, come nell’esempio qui sotto:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

Ti fornirò una RFC in formato Markdown. Genera un documento ADR (Architectural Decision Record) partendo da essa, seguendo il formato Markdown qui sotto.

L’ADR deve essere sintetico, chiaro e documentare:
 • il contesto della decisione
 • la decisione presa
 • le opzioni considerate
 • le conseguenze tecniche

Mantieni un tono tecnico e formale. Inserisci i contenuti coerenti con la RFC ricevuta.

<template>
# ADR: <Titolo della decisione>

- **Stato**: Proposta / Accettata / Rifiutata / Deprecata
- **Data**: <YYYY-MM-DD>
- **Autore/i**: <Nome/i>

## Contesto

<!-- Descrizione del contesto tecnico e organizzativo che ha portato alla necessità della decisione -->

## Decisione

<!-- Decisione architetturale presa in modo chiaro e sintetico -->

## Opzioni considerate

<!-- Breve elenco delle alternative valutate e motivazioni -->

## Conseguenze

<!-- Impatti della decisione su sistema, team, operatività e futuri sviluppi -->

## Collegamenti

- RFC correlata: [link o riferimento]
</template>

<rfc>
...
</rfc>

La decisione presa è:

Specifica il documento RFC di origine racchiudendolo tra i tag <rfc></rfc>, quindi aggiungi i punti chiave della decisione architetturale che desideri sintetizzare. Ecco un esempio pratico:

1

Utilizzo di Google Pub/Sub per una gestione serverless

Il risultato finale ottenibile è come quello che segue:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# ADR: Adozione di Google Pub/Sub per Comunicazione Event-Driven tra Microservizi

- **Stato**: Accettata
- **Data**: 2025-05-03
- **Autore/i**: Team Architettura

## Contesto

Con l'evoluzione dell'architettura a microservizi e l'aumento delle interazioni tra servizi come User, Notification e Billing, il sistema ha manifestato i limiti della comunicazione sincrona basata su REST: accoppiamento stretto, difficoltà di scalabilità e resilienza ridotta. Per supportare meglio i flussi asincroni, si è valutata l’introduzione di una soluzione di messaggistica event-driven. L’analisi si è focalizzata sull’adozione di un message broker capace di supportare pub/sub e request/reply, con requisiti di sicurezza (mTLS), osservabilità (OpenTelemetry) e semplicità operativa.

## Decisione

È stato deciso di adottare **Google Pub/Sub** come sistema di messaggistica principale per la comunicazione event-driven tra microservizi.

## Opzioni considerate

- **NATS**: inizialmente proposto per la sua leggerezza e supporto a pattern pub/sub e request/reply, ma scartato per la complessità operativa aggiuntiva e la necessità di gestione infrastrutturale in ambienti ibridi.
- **Apache Kafka**: escluso per l’elevato overhead operativo e per essere sovradimensionato rispetto agli attuali requisiti.
- **Google Pub/Sub**: scelto per la natura completamente gestita (serverless), l’integrazione nativa con GCP, la sicurezza integrata, la scalabilità automatica e il supporto alle esigenze di deployment cloud-first.

## Conseguenze

- **Sistema**: aumenta la resilienza e il disaccoppiamento tra microservizi grazie alla comunicazione asincrona.
- **Team**: formazione necessaria sull’uso di Google Pub/Sub e design event-driven, ma semplificazione della gestione infrastrutturale.
- **Sicurezza**: si sfruttano i meccanismi nativi di IAM e autenticazione tramite workload identity GCP.
- **Observability**: integrazione con Cloud Trace e OpenTelemetry per il tracciamento distribuito.
- **Portabilità**: ridotta portabilità on-premise rispetto a NATS, compensata dalla gestione semplificata e dalla priorità al cloud.

## Collegamenti

- RFC correlata: RFC-EVENTDRIVEN-NATS

Altri tipi di documenti tecnici generabili con AI 📝

L’approccio descritto non si limita a RFC e ADR: puoi sfruttare AI e template Markdown per produrre una vasta gamma di documentazione tecnica, tra cui:

  • Guide operative (runbook, how-to, troubleshooting)
  • Documenti di architettura (diagrammi, overview, decision log)
  • Specifica API (OpenAPI/Swagger, esempi d’uso, tabelle parametri)
  • Checklist di sicurezza e compliance
  • Manuali utente e FAQ tecniche
  • Documentazione di onboarding per nuovi membri del team
  • Changelog e release note
  • Test plan e casi d’uso

Basta definire un template chiaro, fornire i punti chiave e lasciare che l’AI faccia il lavoro sporco (ma ricordati sempre di rivedere il risultato!).

Best practice per prompt e template efficaci 🏆

  • Sii specifico: più dettagli fornisci, meno dovrai correggere dopo
  • Chiedi sempre il formato desiderato (es: elenco, tabella, RFC…)
  • Rivedi sempre l’output: l’AI non è infallibile (ma nemmeno tu)
  • Personalizza il tono: puoi chiedere formalità, ironia, sintesi…
  • Documenta i tuoi template: così il team non dovrà reinventare la ruota ogni volta

Conclusione 🎯

L’AI generativa non sostituisce la competenza umana, ma può renderci più produttivi e meno stressati quando si tratta di documentazione tecnica. Sfrutta template, prompt ben scritti e un pizzico di creatività: la tua documentazione (e il tuo team) ti ringrazieranno!

Ultimo aggiornamento il
Prompt Engineering 🤖Diagrammi architetturali con AI generativa 🗺️