Technical Documents with Generative AI 🤖

Why use AI for technical documentation? 🤔

Writing technical documentation is a bit like going to the dentist: everyone knows it’s important, but no one wants to do it. Generative AI, though, can transform this experience into something (almost) pleasant! Thanks to language models, today we can generate clear, coherent and even personalized documents, starting from simple prompts and templates.

You save time (and headaches)
Reduce errors and oversights
Standardize style
Facilitate collaboration

⚠️ Important note: Always remember to double-check documents generated by the AI: even the most advanced models can make mistakes, omissions or misunderstandings. The same prompt can produce different results: always verify correctness, consistency and adherence to your team’s standards before using or sharing documentation.

The advantages of Markdown templates 📋

Markdown is the lingua franca of technical documentation: simple, readable and perfect for being processed by both humans and machines (and developers who don’t like frills). Using Markdown templates with AI means:

Structure information clearly
Reduce the “fantasy novel” syndrome
Encourage reusability and consistency across documents
Be easily interpreted by major SaaS documentation management platforms
Enable versioning via control systems like Git

How AI-assisted generation works 🪄

Define the key points: what do you want to communicate? What are the essential pieces of information?
Choose (or create) a template: preferably one already tested by the team.
Prompt the AI: provide the key points and ask it to populate the template.
Review and customize: the AI is good, but you’re better! Add details, correct inaccuracies and adapt the tone.

Pro tip: the more details you provide in the prompt, the more accurate and useful the documentation will be. The AI doesn’t read minds (yet).

Practical example: RFC generated with AI 🚀

Here is an example of a prompt and the result you can get with a Markdown template for 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:

By combining it with key points like in the example that follows:

1
2
3
4
5
6
7
8


- Introduce event-driven communication between microservices
- Use NATS as message broker for pub/sub and request/reply
- Goal: reduce coupling between services and improve scalability
- Services involved: User Service, Notification Service, Billing Service
- NATS chosen for lightness, performance and ease of use
- Evaluated Kafka alternative, discarded for unnecessary complexity
- Security with mTLS, event tracking with OpenTelemetry
- Gradual rollout: alongside REST, then progressive migration

By using the prompt with template and key points in ChatGPT you can get a document like the following:

 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.

From RFC template to ADR: automate architectural decisions 🏗️

You’ve produced a detailed RFC with AI, but now you need a clear, summarized architectural decision? No problem: you can ask the AI to transform the RFC into an ADR (Architectural Decision Record) using a dedicated template. This way you get a concise trace, easily consultable and ready to share with the team (or forgotten in a folder, as per tradition).

The process is simple: provide the RFC to the AI, ask it to extract the key points and adapt them to ADR format. This way, the history of architectural decisions stays documented and accessible, without having to rewrite everything from scratch.

The AI can generate the ADR starting from the RFC, extracting key points and adapting the format. Indicate the original RFC between <rfc></rfc> tags and add a summary of the decision to the key points, as in the example below:

 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 è:

Specify the original RFC document by wrapping it between <rfc></rfc> tags, then add the key points of the architectural decision you want to summarize. Here’s a practical example:

1

Using Google Pub/Sub for serverless management

The final result you can get is like the following:

 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