Introduzione¶
Il problema¶
Chi produce documentazione tecnica su strumenti digitali affronta un paradosso: nel momento in cui un manuale viene distribuito, inizia a diventare obsoleto. Gli strumenti evolvono, le interfacce cambiano, nuove funzionalità vengono aggiunte. Il PDF inviato via email tre mesi fa contiene già informazioni superate.
Il problema non è solo tecnico. È un problema di modello distributivo. Un documento statico (PDF, dispensa cartacea, allegato email) una volta consegnato sfugge al controllo dell'autore. Gli aggiornamenti richiedono una nuova distribuzione, che raramente raggiunge tutti i destinatari originali. Chi ha scaricato la versione 1.0 difficilmente tornerà a cercare la 1.1.
Per contenuti che cambiano lentamente questo è accettabile. Per documentazione su strumenti AI, che evolvono a ritmo mensile quando non settimanale, diventa insostenibile.
La soluzione¶
La risposta è spostare la documentazione sul web, in un formato che permetta aggiornamenti continui mantenendo un URL stabile. Chi consulta il manuale trova sempre la versione corrente. Chi deve produrre la documentazione può aggiornarla senza preoccuparsi della redistribuzione.
Ma "pubblicare sul web" può significare molte cose. Un blog WordPress, un Google Doc condiviso, una pagina Notion, un wiki. Ciascuna opzione ha compromessi diversi in termini di controllo, portabilità, costi, complessità.
La soluzione adottata in questo progetto si basa su tre principi:
Separazione tra contenuto e presentazione. I contenuti sono scritti in Markdown, un formato di testo semplice e portabile. La trasformazione in sito web avviene automaticamente. Se un domani si volesse cambiare piattaforma, i contenuti restano utilizzabili.
Controllo completo sull'infrastruttura. Nessun vendor lock-in, nessun abbonamento a piattaforme proprietarie. Gli strumenti sono open source, l'hosting è gratuito (GitHub Pages), il dominio è di proprietà dell'autore.
Automazione del processo di pubblicazione. Modificare un contenuto e pubblicarlo richiede pochi minuti. Non serve conoscere HTML, CSS, o configurare server. Si modifica un file di testo, si salva, il sito si aggiorna automaticamente.
Il risultato¶
Un sistema che permette di:
- Scrivere documentazione in formato testo semplice (Markdown)
- Pubblicarla automaticamente su un sito web professionale
- Aggiornarla in qualsiasi momento con modifiche immediate
- Mantenere uno storico completo delle versioni
- Generare PDF quando servono (per corsi in aula, distribuzione offline)
- Ospitare più manuali sotto lo stesso dominio
- Collaborare con altri autori su singoli contenuti
Il costo operativo è vicino allo zero: l'hosting su GitHub Pages è gratuito, gli strumenti sono open source. L'unico costo eventuale è GitHub Pro (4$/mese) se si desidera mantenere privati i file sorgente durante lo sviluppo.
Perché non usare il proprio sito?¶
Chi ha già un sito web (WordPress, Wix, Squarespace, o altro) potrebbe chiedersi: perché non pubblicare i manuali lì?
È una domanda legittima. La risposta dipende da cosa si vuole ottenere.
Vantaggi di una piattaforma separata:
Indipendenza dalla struttura esistente. Un sito WordPress nato per altri scopi (portfolio, blog, presentazione aziendale) ha una struttura pensata per quei contenuti. Inserirci documentazione tecnica richiede adattamenti, plugin, compromessi. Una piattaforma dedicata nasce già ottimizzata per quel tipo di contenuto.
Formato neutro e portabile. I contenuti in Markdown sono file di testo che puoi aprire con qualsiasi editor, convertire in altri formati, riutilizzare in contesti diversi. Un post WordPress è intrappolato nel database del CMS.
Versionamento nativo. Ogni modifica è tracciata automaticamente. Puoi vedere cosa è cambiato, quando, tornare a versioni precedenti. WordPress non offre questo senza plugin aggiuntivi.
Collaborazione strutturata. Se lavori con altri autori, il sistema di pull request permette revisioni e approvazioni prima della pubblicazione. Nessun rischio di sovrascritture accidentali.
Performance e sicurezza. Un sito statico è veloce (niente database da interrogare) e sicuro (niente CMS da aggiornare, niente vulnerabilità da patchare).
Costi prevedibili. Hosting gratuito su GitHub Pages. L'unico costo è il dominio, se ne vuoi uno personalizzato.
Scalabilità. La stessa infrastruttura può ospitare decine di manuali. Volendo, può diventare un sito completo, acquistando dall'hosting solo il nome di dominio.
Cosa richiede in cambio:
Configurazione iniziale. Il primo setup richiede tempo e una certa dimestichezza con strumenti tecnici (o un assistente AI che guidi il processo). Una volta configurato, la manutenzione è minima.
Scrittura in Markdown. Niente editor visuale integrato come in WordPress: si scrive in un formato testuale con marcatori. È semplice da imparare (le basi si acquisiscono in pochi minuti), e editor come Panwriter, Typora o Obsidian offrono una preview affiancata che mostra il risultato finale mentre scrivi — un buon compromesso per chi preferisce vedere cosa sta producendo.
Processo di pubblicazione. Ogni modifica richiede commit, push, e qualche minuto di attesa per il deploy automatico. Non è immediato come salvare in WordPress.
In sintesi:
Se i tuoi manuali sono pochi, cambiano raramente, e il tuo sito attuale li ospita senza problemi, probabilmente non hai bisogno di questa soluzione.
Se invece produci documentazione che evolve, vuoi controllo completo sui contenuti, preferisci non dipendere da piattaforme proprietarie, o semplicemente cerchi un sistema più pulito e dedicato — questa architettura offre vantaggi significativi.