Errori comuni nella documentazione tecnica

Gli errori ricorrenti non sono di formattazione, ma di perimetro, prove, responsabilità e controllo delle modifiche. Un fascicolo può sembrare completo e restare impossibile da verificare. L'articolo 11 dell'AI Act impone ai fornitori di sistemi ad alto rischio di predisporre la documentazione prima dell'immissione sul mercato o della messa in servizio e di mantenerla aggiornata. L'allegato IV definisce il contenuto minimo. Il regolamento (UE) 2026/1744 semplifica la presentazione per alcune organizzazioni minori, ma non riduce la necessità di dimostrare le affermazioni.

Non ogni impresa SaaS è fornitore di un sistema ad alto rischio: occorre prima confermare confine del sistema, ruolo e classificazione.

1. Documentare il modello, non il sistema

Una model card o scheda del fornitore non descrive prompt, flussi dati, interfacce, supervisione umana, log e azioni successive. Definite il confine e registrate componenti, attori, input, output e controlli. Separate i dati del fornitore dai fatti verificati internamente. La guida all'AI Act per i fornitori SaaS aiuta a stabilire ruolo e perimetro.

2. Partire da un modello narrativo

I template lunghi generano testi plausibili su test e supervisione prima che esistano prove. Iniziate con un indice: requisito, artefatto fonte, versione, titolare, revisore, stato e trigger di aggiornamento. Scrivete la narrazione solo dopo aver controllato le fonti.

3. Confondere policy e prove

Una policy indica cosa dovrebbe accadere; la prova mostra cosa è accaduto per una versione precisa. Requisiti approvati, decisioni architetturali, record dei dati, valutazioni, threat model, approvazioni di rilascio e revisioni del monitoraggio sono prove utili. Ogni elemento deve indicare affermazione, fonte, data, versione e responsabile.

4. Perdere la tracciabilità delle versioni

Diagrammi sovrascritti, test senza versione del modello o dataset e dashboard mutevoli interrompono la catena. Usate un identificativo stabile e collegate ogni artefatto a rilascio, modello, configurazione e data. Dalla produzione il revisore deve poter raggiungere requisiti, architettura, test, rischi, controlli, istruzioni e approvazione.

5. Affidare tutto alla compliance

La compliance coordina lo standard e contesta affermazioni deboli, ma non dovrebbe scrivere fatti tecnici di seconda mano. Prodotto possiede la finalità; ingegneria, architettura e modifiche; dati o ML, le valutazioni; sicurezza, i controlli; release management, ciò che è stato distribuito. Un responsabile centrale governa la copertura senza creare ogni prova.

6. Trattarla come attività una tantum

Modelli, dati, fornitori e rischi cambiano. Aggiungete un controllo d'impatto per modifiche a finalità, confine, modello, dati importanti, prestazioni, supervisione, sicurezza, istruzioni o monitoraggio. La revisione periodica è una rete di sicurezza; il controllo principale deve essere attivato dagli eventi. Una buona struttura accelera anche gli audit.

7. Misurare attività invece della qualità

Il numero di documenti o ticket chiusi non prova che le affermazioni siano sostenute. Misurate completezza al primo passaggio, lacune importanti, eccezioni scadute, link interrotti, versioni incoerenti e tempi di aggiornamento. Se un revisore deve intervistare l'autore, la prova non è autosufficiente.

8. Accettare le affermazioni del fornitore senza verifica

Certificati e model card possono riferirsi a versione, lingua, popolazione o ambiente diversi. Registrate il documento esatto, valutate lo scarto rispetto all'uso e testate il comportamento rilevante. Le informazioni mancanti sono un rischio o una lacuna, non una base per supposizioni.

9. Nascondere le lacune dietro eccezioni vaghe

“Da completare in seguito” non è una decisione controllata. Registrate lacuna, motivo, controllo temporaneo, titolare del rischio, approvazione, azione e scadenza. Un modello chiaro di responsabilità compliance impedisce che le eccezioni diventino permanenti.

Flusso di revisione mirato

1. Confermare confine, ruolo, classificazione, finalità e versione corrente.
2. Creare l'indice dell'allegato IV e collegare fonti controllate.
3. Campionare una dichiarazione su architettura, prestazioni, rischio, supervisione e cambiamento.
4. Verificare identificativi coerenti e risultati riproducibili.
5. Assegnare a ogni lacuna responsabile, rilevanza, azione e data.
6. Integrare trigger in prodotto, fornitori, sicurezza e rilascio.

FAQ

Qual è lo scopo pratico?

Spiegare in modo tracciabile cos'è il sistema, come è stato sviluppato e valutato, quali rischi e controlli si applicano e perché i requisiti sono ritenuti soddisfatti.

Quando si applica ai team SaaS?

L'articolo 11 si applica ai fornitori di sistemi ad alto rischio. Confermate confine, ruolo e classificazione prima di trattare l'allegato IV come obbligo diretto.

Cosa correggere per primo?

Finalità, versione, architettura, valutazione, rischi materiali, supervisione umana, istruzioni e approvazione del rilascio. Prima le contraddizioni e le affermazioni importanti prive di supporto, poi la presentazione.

Fonti

• Regolamento (UE) 2024/1689, in particolare articolo 11 e allegato IV.
• Regolamento (UE) 2026/1744, comprese le semplificazioni della documentazione tecnica.