Nasce docs.ai-know.pro
Nasce un nuovo sito, una costola di questo, dedicato ad ospitare manuali e in futuro forse corsi. Il primo tutorial? Come si fa a creare quel sito.
Chi lavora con strumenti AI conosce il problema: scrivi un manuale, lo distribuisci, e dopo due mesi è già vecchio. L’interfaccia è cambiata, sono arrivate nuove funzionalità, qualche procedura non funziona più come descritta. Il PDF che hai inviato ai partecipanti del corso contiene informazioni superate, ma loro continueranno a consultarlo perché è quello che hanno salvato.
È un problema che mi porto dietro da quando ho iniziato a scrivere documentazione su strumenti come NotebookLM, Claude, i vari generatori di immagini. Strumenti che evolvono a ritmo mensile, a volte settimanale. Ogni nuova versione del manuale significa redistribuire il file, sapendo che raggiungerà solo una parte dei destinatari originali.
La soluzione, in teoria, è semplice: spostare la documentazione sul web. Un URL stabile, contenuti aggiornabili in qualsiasi momento, nessuna redistribuzione necessaria. Chi consulta il manuale trova sempre la versione corrente.
In pratica, implementarla richiede competenze che attraversano sviluppo web, hosting, automazione. Competenze che non tutti hanno, e che richiedono tempo per acquisire.
Spoiler, ho creato un nuovo sito dedicato per ora ai manuali e forse in futuro anche ai corsi, in fondo all’articolo trovate i link sia alla home del nuovo sito sia alla pagina del primo tutorial, con la spiegazione di come si fa a mettere in piedi la struttura che racconto qui.
Mezza giornata con Claude
Il progetto docs.ai-know.pro è nato da un brainstorming con Claude, l’assistente AI di Anthropic. L’obiettivo era trovare una soluzione che fosse sostenibile per chi non è sviluppatore: strumenti open source, costi vicini allo zero, processo di aggiornamento semplice.
L’intero percorso, dall’analisi del problema alla scelta degli strumenti fino al sito funzionante, si è concluso in circa mezza giornata di lavoro. Non perché sia stato tutto facile, ma perché la collaborazione con l’AI ha permesso di esplorare opzioni, valutare trade-off, generare configurazioni e risolvere problemi in tempo reale.
Lo stack finale è composto da MkDocs (un generatore di siti statici per documentazione), Material for MkDocs (un tema professionale con funzionalità avanzate), e GitHub Pages per l’hosting. Tutto gratuito, tutto open source. L’unico costo eventuale è GitHub Pro a 4 dollari al mese, se si vuole mantenere privato il repository durante lo sviluppo.
Il workflow quotidiano è lineare: modifico (o faccio modificare a Claude con la mia supervisione) un file di testo in formato Markdown, faccio commit su GitHub, e in due-tre minuti il sito si aggiorna automaticamente. Non serve conoscere HTML, non serve configurare server, non serve caricare file via FTP.
Il sistema è stato pensato per permettere all’utente di stampare la versione pdf del capitolo che sta leggendo, all’inizio sotto al titolo si trova infatti un pulsante specifico per questa azione. In questo modo chi si trova a suo agio con la versione pdf può stamparla.
Il primo manuale: come replicare il sistema
Il primo contenuto pubblicato su docs.ai-know.pro è, volutamente, la documentazione del sistema stesso. Un manuale che spiega come creare manuali online con questo approccio.
Non è un tutorial passo-passo nel senso tradizionale. È il racconto di un flusso di lavoro, delle scelte architetturali che lo sostengono, e di come la collaborazione umano-AI può accelerare progetti di questo tipo. Include le configurazioni necessarie, i passaggi per il setup, e le riflessioni sul processo.
L’idea è che chiunque abbia esigenze simili, che sia un formatore, un insegnante, un documentalista, possa valutare se questo approccio fa al caso suo e, se decide di procedere, abbia tutti gli elementi per replicarlo.
Cosa arriverà
docs.ai-know.pro ospiterà progressivamente i manuali che produco per i corsi e per la divulgazione. Il prossimo sarà probabilmente una versione aggiornata del manuale su NotebookLM, che nella versione PDF attuale è già superato dalle novità introdotte negli ultimi mesi.
Il vantaggio di questo sistema è che gli aggiornamenti saranno immediati e trasparenti. Quando Google aggiungerà una nuova funzionalità a NotebookLM, il manuale potrà essere aggiornato lo stesso giorno, e chi lo consulta troverà subito le informazioni corrette.
Per chi volesse esplorare: docs.ai-know.pro
Il manuale sulla creazione di manuali online è qui: docs.ai-know.pro/mkdocs-ghpages/
