Il manuale di NotebookLM su docs

Nel post precedente ho parlato della nascita di docs.ai-know.pro, il nuovo spazio per la documentazione tecnica. Ora pubblico il primo manuale migrato in questo formato, quello su NotebookLM che avevo rilasciato a maggio scorso come PDF.

Per ora è una trasposizione fedele del contenuto originale, ancora fermo al 3 maggio 2025, ma ora ho l’infrastruttura per mantenerlo aggiornato senza dover rigenerare e ridistribuire PDF ogni volta che NotebookLM introduce nuove funzionalità.

Alla fine dell’articolo c’è il link diretto.

Perché documentazione web invece di PDF

Il PDF ha senso per contenuti stabili: un libro finito, una guida che fotografa uno stato definitivo. Per strumenti che evolvono continuamente serve qualcosa di diverso. La documentazione web risolve tre problemi pratici.

• L’aggiornabilità: modifico un file, faccio push su GitHub, il sito si aggiorna automaticamente. Chi ha salvato un link vede sempre l’ultima versione senza dover scaricare nulla.

• La tracciabilità: ogni modifica è versionata su Git. Posso vedere cosa è cambiato, quando e perché. Volendo potrei anche pubblicare in automatico un changelog.

• Il doppio formato: il manuale resta fruibile sia come pagina web sia come PDF. Sotto al titolo c’è un pulsante per scaricare il PDF, che viene generato al momento e quindi riflette sempre l’ultima versione del contenuto web.

Il workflow che ho scelto, MkDocs con GitHub Pages, non è una soluzione innovativa, è semplicemente appropriata. La usano tantissimi progetti open source per la documentazione ufficiale, funziona bene e fa quello che serve.

Come è andata praticamente

Ho lavorato con Claude per trasformare il documento Word originale in un sito di documentazione funzionante. Non nel senso che Claude ha fatto tutto da solo mentre io guardavo, ma nel senso che ognuno ha fatto la sua parte.

Io ho deciso cosa fare, come organizzarlo e perché. Ho verificato ogni passaggio, testato il risultato, preso tutte le decisioni su contenuto e struttura. Claude ha convertito il documento Word in markdown strutturato, mi ha guidato nella configurazione tecnica del sistema, ha creato gli script di automazione e risolto i problemi che emergevano.

Qualche esempio concreto. Il manuale originale era un documento Word di 14 capitoli con immagini, formattazione, note. Claude l’ha trasformato in 14 file markdown separati preservando la struttura e convertendo la formattazione in sintassi markdown. Io ho verificato capitolo per capitolo che non si fosse perso nulla. Non ha saputo estrarre direttamente le immagini dal documento, le ho aggiunte io dopo. Ma ha creato la struttura del repository e inserito nei markdown i placeholder nei punti giusti, a me è bastato salvare le immagini con i nomi corretti.

Non avevo mai configurato un repository Git locale collegato a GitHub. Claude mi ha guidato passo per passo: inizializzare Git, configurare il remote, fare il primo commit. Poi mi ha creato script PowerShell per automatizzare commit e push nelle sessioni successive.

Il sito genera automaticamente anche i PDF scaricabili. Serviva uno script che estraesse la struttura dai file markdown, generasse un indice e assemblasse tutto nell’ordine corretto. Claude ha configurato l’ambiente, scaricato le librerie necessarie, scritto lo script, testato, debuggato. Quando ho chiesto modifiche, tipo spostare l’indice dopo la copertina o rimuovere la numerazione delle pagine, le ha implementate immediatamente.

Quando si è presentato un problema Claude ha analizzato il log, identificato il problema, aggiustato la configurazione. Quando volevo cambiare l’ordine dell’indice nel PDF ha modificato lo script di aggregazione e rigenerato tutto.

Cosa ho capito lavorando così

Si potrebbe dire che abbassa drasticamente la barriera d’ingresso. Infatti ho creato un sistema di documentazione professionale senza essere uno sviluppatore. Non ho dovuto passare giorni a studiare MkDocs, Git, GitHub Actions perché Claude conosceva già questi strumenti e mi ha guidato nell’usarli correttamente. Però secondo me non credo metta tutti sullo stesso piano, chi è portato per l’analisi e sa chiedere sarà molto avvantaggiato con l’uso di questi strumenti. Di fatto l’uso di AI sposta la richiesta di professionalità dal sapere fare le cose al sapere analizzare e chiedere.

Certamente accelera l’esecuzione, attività che se avessi dovuto fare da solo avrei impiegato giorni, sono state completate in ore, come la conversione del documento, la configurazione del workflow, la generazione PDF. Claude è “veloce” in senso astratto, ma soprattutto elimina il dover cercare documentazione, capire sintassi, debuggare errori da zero.

C’è anche l’aspetto della qualità, ogni file è stato generato seguendo le convenzioni corrette, la struttura del progetto è risultata pulita e mantenibile.

Infine, per me il più rilevante, non sostituisce l’umano. Tutte le decisioni importanti le ho prese io, cosa includere, come organizzarlo, quali compromessi accettare. Claude proponeva soluzioni, io valutavo se erano appropriate. La responsabilità finale resta sempre mia, e questo non cambia.

Accedi al manuale

Per ora si tratta ancora della versione originale del 3 maggio 2025. Va dettto che le cose scritte continuano ad essere corrette, per cui il manuale continua ad essere utile.
Gli aggiornamenti per coprire le funzionalità più recenti arriveranno nelle prossime settimane. Quando pubblicherò aggiornamenti significativi lo segnalerò con un articolo dedicato.

Per accedere al manuale basta cliccare sul pulsante.

VAI AL MANUALE