Se il tuo ERP sa configurare il prodotto, ma il manuale nasce ancora dal file più simile, c’è uno scarto evidente tra come costruisci il prodotto e come costruisci le istruzioni.
Il prodotto viene configurato con una logica industriale. Le istruzioni, invece, vengono ancora ricostruite a mano.
Di solito non dipende da come sono scritte le istruzioni. Dipende da come le fai nascere, da dove le recuperi e da quante operazioni manuali devi fare prima di pubblicarle.
Qui non parlo dei prototipi veri: quelli in cui ogni volta riparti da un foglio bianco, cambi architettura, ripensi la logica di funzionamento, rifai la distinta e documenti qualcosa che non assomiglia quasi per niente al prototipo precedente.
Lì il tema è un altro, e merita un ragionamento a parte.
Parlo del caso molto più frequente: prodotti che vengono chiamati “a commessa”, ma che in realtà partono da famiglie, varianti, optional, mercati e lingue, a cui poi si aggiungono contenuti specifici per la singola commessa.
Magari nessuno ha messo la configurazione in una matrice chiara. Magari quella matrice non esiste ancora in forma esplicita, ordinata, pronta da usare. Magari è sparsa: un pezzo nell’ERP, un pezzo nel configuratore commerciale, un pezzo nella distinta base, un pezzo nella testa di chi vende, progetta o segue la produzione.
Però quella logica esiste: solo che spesso non è ancora diventata una struttura documentale.
Basta poco per essere già dentro una logica di configurazione: un gruppo A oppure B, un optional presente o assente, un mercato che cambia lingua, presa, avvertenze o dati di installazione.
Anche certe commesse “custom” rientrano: layout antinfortunistico, dati di trasporto, disegni di installazione, funzioni aggiuntive o procedure specifiche. La condizione è una sola: devono entrare in punti prevedibili del manuale.
In quel caso non sei un’eccezione. Sei uno dei casi in cui il file-per-file comincia a fare più danni di quanti ne risolva.
Perché il prodotto ha già una logica di configurazione.
Il manuale, invece, spesso viene ancora rattoppato.
E questa è una contraddizione industriale.
Il file più simile è la scorciatoia che ti porta fuori strada
Devi preparare il manuale di una nuova configurazione di prodotto. Non parti da zero, perché sarebbe assurdo: molte informazioni esistono già. Quindi cerchi il manuale più simile.
Fin qui sembra anche ragionevole.
Poi però comincia il giro dei file. Apri il manuale più recente, ma la configurazione non è quella. Apri quello del prodotto più simile, ma è vecchio. Apri il manuale già disponibile nella lingua che ti serve, ma non sai se la traduzione corrisponde davvero alla versione tecnica che stai usando. Apri un quarto file perché lì c’era una procedura scritta meglio.
Dopo mezz’ora non stai più preparando il manuale. Stai cercando di capire quale pezzo puoi copiare senza portarti dietro un errore.
Il file che ti servirebbe dovrebbe avere tre caratteristiche insieme: essere recente, avere la configurazione giusta ed essere già disponibile nella lingua che ti serve. Di solito ne hai due su tre, quando va bene.
E sulle istruzioni due su tre non basta.
A quel punto hai quattro file aperti e stai facendo archeologia documentale: italiano vecchio, italiano nuovo, manuale già tradotto, manuale del prodotto quasi uguale.
Il problema è proprio quel “quasi”. Nel prodotto, “quasi giusto” non basta. Nelle istruzioni nemmeno. È lì che nasce il patatrac: non nel pezzo completamente sbagliato, ma nel pezzo abbastanza simile da sembrare recuperabile.
Perché non stai più costruendo istruzioni. Stai facendo taglia e cuci. Prendi una descrizione da un file, una tabella da un altro, una procedura da un terzo, un pezzo già tradotto da un quarto. Poi devi capire se la frase che stai spostando è davvero la stessa, se il contenuto corrisponde, se la versione tecnica è ancora valida, se l’optional è compatibile, se quel mercato richiede qualcosa di diverso.
Magari sei bravissimo. Hai memoria, esperienza, occhio. Sai dove cercare. Sai quali cartelle evitare. Sai che una procedura buona non è nell’ultimo manuale, ma in una commessa precedente. Sai che quella traduzione affidabile è finita in una sottocartella che nessuno aprirebbe mai.
Tutto questo dimostra esperienza, non metodo. Resta il fatto che stai facendo manovalanza.
E la manovalanza, quando viene moltiplicata per decine o centinaia di operazioni, produce errori. Non per incapacità. Per statistica.
Non serve fare conti precisi. Ogni operazione manuale è un’occasione di errore. Se moltiplichi tagli, confronti, recuperi, adattamenti e incolli, prima o poi qualcosa finisce nel manuale sbagliato, nella lingua sbagliata, nella versione sbagliata o nel punto sbagliato.
E sulle istruzioni non puoi cavartela dicendo: “Sì, ma era quasi uguale”.
Le istruzioni devono riferirsi al prodotto effettivamente consegnato: con quella configurazione, quella matricola, quel mercato, quella lingua.
Quando il “taglia e cuci” non regge più
Se hai poche varianti, poche lingue, poche revisioni e pochi mercati, il “taglia e cuci” può anche sembrare gestibile. Non bene, ma abbastanza da tirare avanti: ti arrangi, sistemi, fai un po’ di copia-incolla, ti ricordi dove sono le cose.
Quando invece aumentano configurazioni, optional, lingue, mercati, revisioni e commesse simili ma non identiche, il file-per-file diventa una macchina che produce doppioni. E i doppioni, prima o poi, diventano versioni parallele dello stesso contenuto.
Ogni manuale contiene pezzi comuni: avvertenze generali, descrizioni ricorrenti, procedure simili, dati tecnici, manutenzioni, traduzioni già fatte. Se li copi in un nuovo file, li trasformi in doppioni. E ogni doppione, da quel momento, può essere aggiornato, tradotto o dimenticato in modo diverso dagli altri.
Forse qualche volta, creando un nuovo manuale, hai avuto l’impressione di avere pochi contenuti da recuperare e molti contenuti da produrre.
In realtà, spesso il problema è l’opposto: hai troppi contenuti. Solo che sono stati copiati, ricopiati, adattati, tradotti, ritoccati e sepolti in documenti diversi.
A quel punto l’archivio diventa grande, ma non diventa governato. Hai più file, più cartelle, più versioni, ma non più controllo.
E il “taglia e cuci” ha prodotto un Frankenstein documentale impossibile da gestire.
Non l’hai costruito tu. È il risultato di un modello che per anni è sembrato normale: documenti, cartelle, Word, InDesign o qualunque altro software nato per elaborare file.
Non sembrava una cattiva idea. Il manuale era un file, quindi si lavorava sui file. E per molto tempo non ci sono state vere alternative.
Oggi, però, quel modello si può superare.
Prima però c’è un altro pezzo del problema da guardare in faccia: anche quando trovi i contenuti giusti, il documento resta un oggetto unico.
Il problema della pagina 132
Un manuale tradizionale comincia a pagina 1 e finisce a pagina 132. Finché pagina 132 non è a posto, non puoi chiuderlo, approvarlo, pubblicarlo o mandarlo in traduzione senza portarti dietro il rischio di riaprirlo.
Se sei in ritardo, non puoi buttare tre persone dentro lo stesso file e moltiplicare la velocità. Una lavora, le altre aspettano. Oppure si fanno copie, capitoli separati, pezzi via mail. Poi qualcuno deve rimettere insieme tutto e controllare che nessuno abbia lavorato sulla versione sbagliata.
Puoi spezzare il manuale in capitoli, certo. A volte aiuta. Ma se la logica resta quella del file, hai solo trasformato un documento grande in tanti documenti più piccoli. Magari attenui un pezzo del problema, ma non cambi la radice. E intanto hai moltiplicato il numero di file da governare.
Il punto è che, anche se dividi il manuale in capitoli, l’informazione continua a vivere nel file.
E quando l’informazione vive nel file, ogni collaborazione diventa coordinamento manuale: chi ha aggiornato cosa, quale versione è buona, quale lingua è allineata, quale capitolo è stato ricomposto, quale PDF è quello finale, quale cartella contiene davvero l’ultima release.
Quando il sistema resta fondato sui file, le regole non stanno nel processo. Stanno nella testa di qualcuno. È lì che nasce la dipendenza dalla memoria storica.
In molte aziende il sistema documentale funziona perché una persona sa dove sono le cose. Sa che una procedura buona è in una commessa di qualche anno fa. Sa che la traduzione corretta non è nell’ultimo manuale, ma in un archivio precedente. Sa che una certa variante ha cambiato nome tre volte. Sa che in quella cartella non devi entrare, anche se sembra la più recente.
Questa esperienza è preziosa.
Ma se resta nella testa di una persona, non è un processo. È una dipendenza.
E ogni dipendenza, prima o poi, presenta il conto.
Non importa quanto sia bravo chi oggi tiene insieme il sistema. Il prossimo che eredita quel caos non può entrare nella testa di chi lo ha costruito per anni. Non può ricostruire scorciatoie, eccezioni e abitudini solo perché gli hanno passato le cartelle. Perché non eredita una struttura: eredita cartelle, sottocartelle, file, eccezioni, abitudini e scorciatoie che funzionavano solo perché qualcuno le aveva in testa.
Puoi sopravvivere così per anni, con cura certosina e tanta pazienza. Ma sopravvivere non significa avere un sistema che puoi far crescere, trasferire o automatizzare senza prima rimettere ordine.
Il manuale deve diventare il risultato, non la sorgente
Se vuoi rottamare in modo definitivo un impianto documentale rischioso e inefficiente, e automatizzare la pubblicazione dei manuali in modo sicuro, devi andare oltre al “taglia e cuci”.
Non basta fare più attenzione quando copi, né organizzare meglio le cartelle.
Il salto vero è un altro: smettere di usare il manuale come posto in cui vive l’informazione.
Il manuale deve diventare il risultato di un processo che richiama informazioni già governate.
La sorgente vera non è il documento. Sono le informazioni di prodotto: procedure, avvertenze, descrizioni, dati tecnici, tabelle, istruzioni di installazione, manutenzioni, contenuti validi per un certo mercato, contenuti di commessa, contenuti legati a una certa matricola o a una certa configurazione.
Quelle informazioni non devono stare sepolte dentro manuali già chiusi. Devono diventare moduli: pezzi riconoscibili, versionati, traducibili, classificati, con un campo di validità preciso.
Non “un paragrafo che mi ricordo di aver visto da qualche parte”, ma un pezzo di informazione che il sistema può riconoscere e richiamare.
Può valere per una famiglia di prodotto, per una variante, per un optional, per un mercato, per un tipo di documento, per una commessa, per una matricola. Può essere generale oppure specifico. Può essere approvato, superato o in revisione. E se per una certa configurazione dovrebbe esistere ma non esiste, il sistema deve mostrarti il buco.
Quando l’informazione è ben governata, il manuale non nasce più dal file precedente. Nasce dall’assemblaggio controllato dei moduli applicabili.
Non stai più producendo un manuale alla volta.
Stai costruendo la capacità di generare il manuale giusto.
Produrre un manuale significa chiudere un documento.
Costruire una capacità produttiva documentale significa creare il sistema che ti permette di produrre il prossimo manuale con meno manovalanza, meno incertezza e meno rischio di pubblicare istruzioni non aderenti alla configurazione reale.
È lo stesso salto che fai quando passi dal costruire ogni pezzo a mano al progettare uno stampo. Il primo pezzo richiede lavoro. Ma dal secondo in poi non riparti più da zero: usi una capacità produttiva che hai già costruito.
Come nasce una fabbrica documentale
Il principio non è complicato. La realizzazione richiede metodo, ma la logica ruota attorno a quattro elementi.
- Un patrimonio ordinato di contenuti modulari
Non una cartella messa meglio, ma un deposito unico in cui le informazioni vivono come unità richiamabili, non come pezzi sepolti dentro manuali già chiusi.
- Metadati e tassonomie
I metadati non servono a fare ordine estetico. Servono a dichiarare il campo di validità di un contenuto: prodotto, variante, optional, mercato, lingua, tipo di documento, commessa, matricola. Il sistema deve sapere dove quel contenuto è valido e dove no.
Un contenuto senza campo di validità è come un ricambio senza codice a magazzino: magari è quello giusto, ma quando ti serve non puoi trovarlo in modo affidabile.
- Una matrice di configurazione
Ovvero una struttura che dice com’è fatto il prodotto da documentare. Variante A, variante B, optional presenti, optional assenti, mercato, lingua, eventuali specificità di commessa.
- Un modello master del manuale
Non è il manuale. È la sua struttura logica. Decide dove devono comparire le informazioni, in quale ordine, a quale livello e con quali condizioni.
Nel modello master ci sono punti in cui la struttura “chiede” un contenuto: qui serve la procedura di manutenzione del gruppo installato, qui il contenuto di sicurezza valido per quel mercato, qui il dato specifico di commessa. Il sistema arriva in quel punto e cerca il modulo valido.
Arrivato a questo punto, il CCMS — il sistema che gestisce i contenuti modulari — legge la configurazione, incrocia le tassonomie con il campo di validità dei moduli, cerca i contenuti applicabili e richiama quello giusto al posto giusto.
In questo punto non ti serve creatività. Ti serve un comportamento prevedibile: data una configurazione, il sistema deve richiamare i contenuti applicabili e lasciare fuori gli altri.
Se trova un solo modulo valido, lo inserisce. Se non ne trova nessuno, ti dice che manca qualcosa. Se ne trova due dove dovrebbe essercene uno solo, ti mostra il conflitto.
Il cuore della fabbrica documentale è qui: il sistema applica regole verificabili a contenuti governati.
Il PDF finale è solo l’output. La schermata elegante fa scena, ma non governa il processo. Il nome dello strumento conta molto meno di quanto sembra.
E se il sistema ti dice “manca”, non è un problema: è esattamente quello che vuoi sapere prima di pubblicare. Meglio scoprire il buco lì che dopo aver chiuso un manuale incompleto, incoerente o riferito alla configurazione sbagliata.
Attenzione però: non è il CCMS in sé a produrre il risultato. Il CCMS è l’infrastruttura. La differenza la fa il metodo della fabbrica documentale: moduli classificati bene, matrice leggibile, modello master costruito con criterio, regole di applicabilità sensate.
Se butti nel sistema lo stesso caos che avevi nelle cartelle, hai solo spostato il caos in un posto più costoso.
L’IA può aiutare. Ma non deve decidere il manuale.
A questo punto è inevitabile parlare di IA, perché oggi molti provano a infilare agenti e generatori di testo in qualunque processo che abbia dentro dei documenti.
L’IA, dentro un sistema modulare progettato bene, può fare cose molto utili.
Può aiutarti a preparare i contenuti: pre-taggare moduli, proporre metadati, trasformare appunti e note di reparto in una prima bozza, uniformare stile e terminologia, perfino aiutare su immagini e illustrazioni quando il processo è governato.
Il problema nasce quando si confonde il supporto alla preparazione dei contenuti con la decisione su quali contenuti devono entrare nel manuale.
L’IA può preparare pezzi, ma non governare l’assemblaggio: non deve decidere che cosa entra nel manuale di un prodotto configurato, destinato a un mercato preciso, con istruzioni pubblicate nella lingua corretta.
Quella decisione deve stare in un sistema che applica regole verificabili.
Se metti un agente sopra un archivio che non distingue bene varianti, versioni e lingue, non hai fatto automazione. Hai solo dato velocità al caos.
Un agente può produrre un testo plausibile e può anche arrivare spesso alla risposta giusta. Ma “spesso” non è il livello di garanzia che ti serve quando devi generare istruzioni per un prodotto reale.
Qui servono regole: se quella configurazione monta un certo gruppo, entra quel contenuto; se un contenuto manca, il sistema lo segnala; se due contenuti risultano applicabili nello stesso punto, il sistema mostra il conflitto.
Questa non è una conversazione con un agente. È un processo che deve dare risultati verificabili.
Qui non ti serve un agente brillante che interpreta. Ti serve un sistema noioso, preciso, testardo, verificabile, che non si inventa niente.
L’IA sta bene ai bordi, dentro binari chiari. Il centro della fabbrica resta il metodo: contenuti modulari, tassonomie, modello master e regole deterministiche. Prima di far lavorare l’IA, devi aver progettato bene il sistema in cui lavora.
Una macchinetta del caffè per vedere il meccanismo
Per rendere visibile il meccanismo, ho usato una macchinetta del caffè configurabile: un prodotto semplice, dove la logica delle varianti entra in gioco da subito.
La macchinetta ha tre colori, due tipi di ingresso caffè, modulo latte presente o assente, con o senza riscaldatore, modulo zucchero, quattro mercati e una possibile personalizzazione di commessa.
Già così arrivi a oltre cento combinazioni documentali.
Il punto non è la macchinetta. Il punto è vedere il sistema che lavora.
Il sistema non “scrive un manuale”. Richiama i contenuti applicabili: cialde o macinato, latte o niente latte, riscaldatore o no, zucchero o no, mercato corretto, eventuale personalizzazione di commessa.
Su un prodotto reale, la complessità cresce esponenzialmente: optional, gruppi funzionali, mercati, lingue, revisioni, matricole, commesse e anni di storico documentale.
In certi casi, combinando tutte queste variabili, arrivi a gestire migliaia o perfino centinaia di migliaia di configurazioni possibili.
A quel punto non stiamo più parlando di un modo più elegante per fare PDF, ma di una capacità produttiva indispensabile per generare istruzioni coerenti con ogni configurazione reale.
Il primo beneficio non è arrivare prima: è smettere di lavorare al buio.
Non devi più cercare il file meno sbagliato, rifare traduzioni già disponibili o chiederti ogni volta se una procedura vale ancora per quella versione. Il sistema ti mostra che cosa è applicabile, che cosa manca e dove c’è un conflitto.
Poi fai anche prima, certo.
Ma fai prima perché hai tolto operazioni inutili dal processo, non perché hai accelerato lo stesso processo fragile.
Questo è il punto che distingue un’automazione seria da una scorciatoia pericolosa.
Se acceleri un processo fragile, acceleri anche i suoi errori.
Se invece il processo è governato, l’automazione diventa finalmente utile: richiama moduli validati, recupera traduzioni collegate, segnala mancanze, evidenzia conflitti, permette a più persone di lavorare in parallelo e produce un output coerente con la configurazione.
Con un processo così, è normale che il manuale venga vissuto come una multa da pagare: un PDF da produrre perché serve, perché altrimenti la commessa non si chiude, perché il fascicolo deve essere completo, perché “ci vuole”.
Ma questo è il modo più povero di intendere le istruzioni.
Le istruzioni non dovrebbero restare l’ultima seccatura prima della consegna, ma una parte governata del prodotto.
Se configuri il prodotto, devi configurare anche le istruzioni
Se il prodotto è configurabile e il manuale no, hai trovato il punto in cui il processo documentale si è scollegato dal prodotto.
Non perché le istruzioni siano necessariamente fatte male. Ma perché nascono da una logica sbagliata: un documento simile da adattare, invece di una configurazione da documentare.
Il prodotto viene governato con codici, distinte, revisioni, compatibilità e configurazioni.
Le istruzioni vengono spesso ricostruite da file simili, cartelle, memoria storica, compromessi tra variante, versione e lingua, più un numero sproporzionato di operazioni manuali.
Il sistema può reggere finché le varianti sono poche, le lingue sono poche e le modifiche arrivano raramente. Ma quando aumentano configurazioni, mercati, revisioni e commesse simili ma non uguali, quel modo di lavorare non dà più garanzie: non hai più un modo affidabile per sapere prima della pubblicazione se il manuale è completo, coerente e davvero riferito alla configurazione corretta.
E non si risolve con un agente IA lasciato libero nell’archivio.
Si risolve spostando la sorgente del lavoro dal documento alle informazioni di prodotto.
Quando fai questo salto, il manuale non è più un file da rattoppare ogni volta, ma il risultato di una fabbrica documentale che può generarlo in modo controllato.
A un certo punto devi smettere di chiudere manuali uno alla volta e costruire il sistema che li genera corretti.
Scopri come si fa, in concreto
Ho caricato nel Club dei Technical Writers di because un video in cui mostro il meccanismo completo: come una configurazione viene trasformata in un manuale corretto attraverso matrice, moduli, tassonomie, modello master, punti di richiamo e generazione automatica.
È un contenuto riservato ai membri del Club, che puoi provare gratuitamente per 3 mesi. Appena entri, puoi guardare subito l’approfondimento.
Se sei già iscritto al Club dei Technical Writers di because, trovi questo video nella sezione “Webinar e Workshop” con il nome di “Fabbrica automatica dei manuali”. È diviso in due parti: nella prima parte approfondisco i temi di questo articolo sotto forma di video; nella seconda parte faccio vedere l’applicazione pratica nel sistema CCMS.
PS: Se vuoi capire, nei prossimi articoli, come tenere insieme redazione, traduzione e pubblicazione senza caos, senza dipendere dai fornitori e senza mettere a rischio sicurezza e conformità, iscriviti a questa newsletter.
E se leggendo ti è venuto in mente qualcuno che, nella tua azienda o in quella di un cliente, si sente stretto tra il lavoro manuale che non regge più e l’IA fuori controllo che promette miracoli, inoltragli questo articolo.