Manuali tecnici sul web: pubblicare e mantenere

Un manuale tecnico si pubblica scegliendo prima il formato, PDF o guida in linea, e poi un luogo stabile dove ospitarlo, con una procedura di aggiornamento e un canale di assistenza. La scelta del formato decide il resto: un PDF si scarica e invecchia in silenzio, una guida in linea si corregge in un minuto ma richiede manutenzione continua. Chi scrive e chi gestisce il sito devono quindi mettersi d’accordo su chi controlla i link, chi risponde ai lettori e ogni quanto si rilegge il testo.

Come si pubblica e si aggiorna un manuale tecnico sul web?

La pubblicazione si divide in tre passaggi: preparazione dei contenuti, messa in linea e ciclo di revisione. Nella preparazione si scrivono i capitoli in un formato testuale semplice, Markdown o HTML, e si tengono le immagini in una cartella separata con nomi leggibili. Nella messa in linea si sceglie una piattaforma: un sito statico, un blog con CMS o una sezione dentro un sito esistente. Il ciclo di revisione è la parte che quasi tutti trascurano: un manuale tecnico contiene nomi di prodotti, versioni, indirizzi e schermate che cambiano, e senza una data di revisione visibile il lettore non sa se sta leggendo istruzioni valide.

Una pratica utile è la data di ultima modifica in cima alla pagina, con l’indicazione di che cosa è cambiato. Un’altra è separare il testo dalle schermate: se le immagini stanno in una cartella con numeri progressivi, sostituirne una non richiede di riscrivere il capitolo. Chi pubblica guide su Mac, web e hosting trova riferimenti concreti in manuali tecnici sul web, dove i temi trattati vanno dalla configurazione di iOS alle prestazioni di un sito.

Che cosa cambia tra una guida in PDF e una guida in linea?

Il PDF è un oggetto chiuso: una volta distribuito, resta identico a se stesso. Ha tre vantaggi reali, cioè si archivia, si stampa e si legge senza connessione. Ha un difetto altrettanto reale: se una procedura cambia, il file già scaricato non lo saprà mai. Le guide in PDF funzionano bene per documenti normativi, manuali di prodotto con ciclo di vita lungo e materiali che devono restare citabili nella stessa forma.

La guida in linea è un oggetto aperto. Si corregge, si integra e si collega ad altre pagine; i motori di ricerca la trovano e gli aggiornamenti raggiungono subito il lettore. In cambio richiede un indirizzo stabile per ogni pagina, perché un link che cambia rompe i rimandi interni e le citazioni esterne. Se il manuale ha più di venti pagine, la scelta più frequente è ibrida: guida in linea come versione principale e PDF generato periodicamente come copia archiviabile.

Come si organizza l’assistenza di un manuale digitale?

L’assistenza di un manuale non è un help desk generico: è la gestione delle domande che nascono dal testo. Si organizza su tre livelli. Il primo è la pagina delle domande frequenti, costruita raccogliendo le richieste reali e non quelle immaginate in fase di scrittura. Il secondo è un modulo di contatto o un indirizzo di posta dedicato, con la promessa di una risposta e la registrazione di ogni segnalazione. Il terzo è la correzione del manuale: quando la stessa domanda arriva tre volte, il problema non è il lettore ma il paragrafo.

Un registro delle segnalazioni, anche un semplice foglio di calcolo con data, pagina e tipo di errore, permette di capire quali capitoli invecchiano prima. Se il manuale riguarda software, conviene indicare la versione minima e massima supportata: evita risposte su configurazioni che non esistono più.

La ronda dei link e delle versioni

La manutenzione periodica si fa con una ronda, cioè un controllo a intervalli regolari. Serve a verificare che il manuale descriva ancora il mondo reale. Ecco la lista delle operazioni, da eseguire in ordine.

• Aprire ogni pagina e controllare la data di ultima revisione.
• Provare tutti i link esterni e sostituire quelli che restituiscono errore.
• Verificare i nomi dei prodotti e i numeri di versione citati.
• Controllare che le immagini corrispondano alle schermate attuali.
• Rileggere le domande arrivate dall’assistenza e aggiornare le FAQ.
• Controllare che gli indirizzi delle pagine non siano cambiati.
• Annotare le modifiche in un registro con data e autore.

La frequenza dipende dal tema: un manuale su un’app che si aggiorna ogni mese richiede una ronda mensile, un manuale su procedure stabili può bastare ogni sei mesi. La ronda non serve a riscrivere, serve a decidere che cosa va riscritto.

Errori comuni

Il primo errore è pubblicare senza data di revisione: il lettore non può fidarsi di un testo che non dichiara la propria età. Il secondo è affidare tutto a un PDF e considerarlo finito. Il terzo è usare indirizzi di pagina generati automaticamente, che cambiano a ogni ristrutturazione del sito e rompono i rimandi. Il quarto è scrivere l’assistenza come un modulo anonimo, senza registrare le domande: così le stesse richieste tornano e il manuale non migliora. Il quinto è mescolare nel testo istruzioni valide per versioni diverse senza indicarlo.

In sintesi

Un manuale tecnico sul web è un prodotto che continua dopo la pubblicazione. Il formato va scelto in base al ciclo di vita del contenuto, la manutenzione va pianificata con una ronda regolare e l’assistenza va trattata come una fonte di correzioni. Chi pubblica deve poter dire, in ogni momento, quando il testo è stato rivisto l’ultima volta e che cosa è cambiato. La differenza tra un manuale utile e uno dimenticato sta quasi sempre in queste tre abitudini, non nella qualità della prima stesura.

Fonti: w3.org.