Note sulla collaborazione umano-AI¶

Questo manuale, e il sistema che descrive, sono il prodotto di una collaborazione tra un professionista e Claude, l'assistente AI di Anthropic. Questa sezione riflette su come si è svolta quella collaborazione e su cosa suggerisce per l'uso dell'AI in progetti simili.

Come è nato il progetto¶

Il punto di partenza era eliminare i manuali in versione PDF statica: la necessità di mantenere la documentazione sempre aggiornata si scontrava con la realtà che ogni nuova versione significava ridistribuire il file, sapendo che molti destinatari avrebbero continuato a usare quella vecchia.

La soluzione, individuata in un brainstorming tra umano e Claude, è stata spostare la documentazione sul web mantenendo la possibilità di scaricare il PDF per chi ne ha bisogno. L'intero processo, dall'analisi del problema alla scelta degli strumenti fino all'implementazione funzionante, si è concluso in circa mezza giornata di lavoro grazie alla partecipazione attiva dell'AI.

Il ruolo di Claude nel progetto¶

Claude ha contribuito in diverse fasi.

Analisi delle alternative. Prima di scegliere MkDocs e GitHub Pages, Claude ha analizzato diverse opzioni (Docusaurus, Sphinx, GitBook, WordPress con plugin), confrontandole per complessità, costi, funzionalità, portabilità. L'analisi ha permesso una decisione informata invece di una scelta casuale o basata solo su familiarità pregressa.

Progettazione dell'architettura. La scelta tra repository separati o monorepo, tra GitHub Pages e alternative come Netlify o Cloudflare Pages, è emersa da un dialogo iterativo. Claude ha presentato opzioni, evidenziato trade-off e adattato le raccomandazioni man mano che emergevano vincoli e preferenze.

Generazione del codice. I file di configurazione (mkdocs.yml, deploy.yml), la struttura delle cartelle, il workflow di GitHub Actions sono stati generati da Claude. Non copiati da template generici, ma costruiti specificamente per le esigenze del progetto.

Debugging in tempo reale. Quando il primo deploy è fallito (un problema di permessi nel workflow), la diagnosi e la soluzione sono arrivate nel giro di pochi scambi. Claude ha interpretato l'errore, identificato la causa e fornito i passaggi correttivi.

Scrittura della documentazione. Questo stesso manuale è stato scritto da Claude a partire dalla conversazione che ha generato il progetto. Non una trascrizione, ma una rielaborazione che estrae il flusso logico e lo organizza in forma consultabile.

Cosa ha fatto l'umano¶

Il ruolo umano nel progetto è stato di direzione, decisione e verifica.

Definire il problema. L'esigenza di partenza, vale a dire una documentazione aggiornabile, è emersa dall'esperienza professionale, non da un prompt.

Porre vincoli. Il rifiuto di soluzioni con costi ricorrenti significativi, la preferenza per strumenti che minimizzassero i servizi da gestire, la necessità di mantenere la possibilità di generare PDF: questi vincoli hanno guidato l'esplorazione.

Decidere tra alternative. Quando Claude ha presentato opzioni con trade-off diversi, la scelta è stata umana. L'AI può analizzare, ma le preferenze e le priorità restano dell'utente.

Eseguire le azioni. Creare l'account, configurare il DNS, caricare i file, verificare che il sistema funzioni: queste azioni sono state compiute dall'umano, seguendo le indicazioni ma non delegandole.

Validare i risultati. Il giudizio finale su cosa funziona e cosa no, su cosa è chiaro e cosa va riscritto, resta umano.

Osservazioni sul processo¶

Alcune caratteristiche di questa collaborazione meritano nota.

Iterazione, non one-shot. Il progetto non è nato da un singolo prompt ben formulato. È emerso da una conversazione estesa, con domande, dubbi, cambi di direzione. Claude ha seguito il filo, mantenuto il contesto, adattato le proposte.

Competenza ibrida. L'umano ha portato conoscenza del dominio (formazione, documentazione tecnica, esigenze dei destinatari) e capacità di giudizio. Claude ha portato conoscenza tecnica (MkDocs, GitHub Actions, configurazione DNS, architetture possibili) e capacità di generazione. Nessuno dei due avrebbe completato il progetto da solo, almeno non con la stessa efficienza.

Trasparenza del processo. Claude non ha nascosto le proprie limitazioni. Quando non poteva accedere a un repository privato, l'ha detto. Quando un'opzione inizialmente suggerita (Cloudflare Pages per routing multi-repo) si è rivelata più complessa del previsto, ha corretto la rotta.

Documentazione incorporata. La conversazione stessa è diventata materiale per la documentazione. Invece di ricostruire a posteriori cosa si è fatto e perché, il ragionamento era già esplicitato.

Implicazioni per progetti simili¶

Questo caso studio suggerisce alcuni principi per l'uso dell'AI in progetti di documentazione e sviluppo.

Partire dal problema, non dallo strumento. La conversazione più produttiva inizia con "ho questo problema" piuttosto che con "fammi un sito MkDocs". L'AI può esplorare soluzioni se conosce il contesto.

Esplicitare i vincoli. Budget, competenze tecniche disponibili, preferenze, requisiti non negoziabili: più l'AI sa cosa conta, meglio può filtrare le opzioni.

Iterare senza fretta. Le soluzioni migliori nascono dal dialogo. Cambiare idea a metà strada non è un fallimento, è raffinamento.

Verificare, non fidarsi ciecamente. Claude può sbagliare, può non conoscere aggiornamenti recenti, può fraintendere. Il controllo umano non è opzionale.

Documentare mentre si procede. Se la conversazione è il luogo dove si prendono decisioni, è anche il luogo naturale da cui estrarre documentazione. Non rifare il lavoro dopo: usare quello che c'è già.

Un punto di partenza¶

Questo progetto è un esempio, non un modello universale. Altri contesti, altri vincoli, altre competenze produrranno collaborazioni diverse.

Ma l'idea di base, ovvero che un professionista non tecnico possa, con l'assistenza di un'AI, costruire e mantenere un sistema di documentazione professionale, è dimostrata. Non richiede di diventare sviluppatori. Richiede di saper dialogare con chi (o cosa) le competenze tecniche le ha.