Italy 🇮🇹

Documentazione AI-Readable

Al momento c'è molto interesse intorno ad uno strumento di sviluppo chiamato GitHub Copilot, che dispone di funzionalità assistite dall'AI. C'è una percezione errata che questo strumento sia solo per gli ingegneri. Sebbene questo sia parzialmente vero, è anche parzialmente scorretto. Infatti, GitHub Copilot ha una incredibile capacità di trasformare il modo in cui gli ingegneri lavorano. Tuttavia, poiché i metodi di lavoro degli ingegneri cambiano, le organizzazioni devono anche adattarsi. Se sei in una posizione di PM o PO, questo è un problema importante anche per te. Poiché si prevede che gli ingegneri del tuo team svolgano il loro lavoro al meglio, implementando i requisiti definiti nel modo più rapido possibile. In futuro, anche se non sei un ingegnere, dovrai creare documentazione leggibile dall'AI per consentire ai tuoi ingegneri di collaborare con l'AI.

Cultura della documentazione e sviluppo nativo di AI

Negli ultimi anni, la tecnologia dell'AI ha fatto rapidi progressi, con modelli come LLM (Large Language Model) che attirano l'attenzione. GitHub, una piattaforma di sviluppo open source, si è anche avventurata nel campo dello sviluppo di AI. Un esempio di questo è "GitHub Copilot". Interessantemente, lo sviluppo assistito dall'AI e lo sviluppo open source condividono un terreno comune in termini di collaborazione. In particolare, entrambi i metodi prevedono il lavoro con formati basati su documenti come Markdown. I formati come Markdown sono progettati per rappresentare informazioni strutturate e sono più facili da analizzare dall'AI rispetto a file PowerPoint o Excel. Di conseguenza, contribuiscono al miglioramento della qualità del codice generato dall'AI.

L'AI preferisce file CSV semplici rispetto a complessi fogli di calcolo Excel pieni di metadati. Se, ad esempio, tu come PM, elenchi i requisiti del cliente e raccogli le informazioni necessarie per un database. Se i requisiti sono scritti in un file CSV o riassunti in Markdown, gli ingegneri possono facilmente convertirli in codice. Tuttavia, se compili le informazioni in un documento Excel personalizzato alle tue preferenze, gli ingegneri devono prima copiarlo, formattarlo e quindi convertirlo in codice. Quale approccio è migliore?

Inoltre, nello sviluppo open source, la qualità della documentazione può essere direttamente correlata al successo di un progetto. I progetti open source sono aperti a tutti e una documentazione adeguatamente mantenuta consente ai nuovi sviluppatori di partecipare in modo più fluido. Pertanto, la documentazione è altamente valorizzata nello sviluppo open source. In modo simile, nello sviluppo di AI, una cultura della documentazione ben consolidata può portare ad uno sviluppo più efficient e di qualità superiore. Anche se non sei un ingegnere, il tuo linguaggio naturale scritto in Markdown può contribuire significativamente all'output finale, che è il codice. Questo potrebbe essere il codice che rappresenta la logica aziendale, le definizioni delle tabelle o anche gli scenari di test. Il tuo team di sviluppo è pronto ad includere l'AI? Sono stati preparati documenti leggibili dall'AI? Se la risposta è no, devi iniziare a creare un team di sviluppo che sia confortevole per l'AI.

Sviluppo nativo di AI e strategia InnerSource

Abbiamo discusso dello sviluppo open source, ma esiste anche un concetto simile chiamato inner source. InnerSource è un approccio che adotta le migliori pratiche dello sviluppo di software open source all'interno delle organizzazioni che sviluppano software non open source o proprietari. L'obiettivo è promuovere la collaborazione tra le divisioni organizzative e abbattere i silos organizzativi.

InnerSource sta diventando sempre più importante per le aziende per evitare di reinventare la ruota, razionalizzare lo sviluppo per ridurre i costi e creare nuovo valore attraverso la collaborazione.

Come menzionato nella pagina di sviluppo nativo di AI, l'AI tende ad aumentare le capacità degli esseri umani esperti. Le persone senior o esperte all'interno di un'organizzazione che comprendono l'architettura vengono potenziate, mentre ad altre vengono assegnati compiti più semplici.

Tuttavia, poiché l'AI è principalmente addestrata su conoscenze provenienti dal web, non può accedere a domini proprietari, conoscenze riservate all'interno delle organizzazioni o informazioni non pubblicate. Pertanto, se queste informazioni non sono documentate o condivise correttamente all'interno dell'organizzazione, questo rappresenta un problema. Questo problema significa che non solo gli ingegneri non possono accedere alle informazioni, ma anche l'AI come GitHub Copilot non può accedervi.

Le conoscenze che non possono essere ottenute dal web stanno diventando sempre più importanti e rappresentano una competenza essenziale delle aziende. C'è una citazione tratta dal libro introduttivo InnerSource "Getting Started with InnerSource" di O'Reilly:

InnerSource differisce dall'open source classico perché rimane all'interno della visione e del controllo di un'unica organizzazione. L'apertura del progetto si estende su molti team all'interno dell'organizzazione. Ciò consente all'organizzazione di integrare i segreti commerciali differenzianti nel codice senza temere che saranno rivelati a terzi, beneficiando nel contempo della creatività e delle diverse prospettive contribuite dalle persone in tutta l'organizzazione.

Molte aziende si trovano di fronte alla scelta di collaborare con l'AI o essere sostituite dall'AI. È essenziale aggregare le informazioni interne che costituiscono il vantaggio competit ivo di un'organizzazione e farle utilizzare dall'AI. Per raggiungere questo obiettivo, la documentazione con leggibilità dell'AI è indispensabile.

Per quanto riguarda InnerSource, esiste già una comunità matura in cui vengono condivisi i metodi per realizzare la co-creazione all'interno delle organizzazioni e creare documentazione. Accedi a questa comunità e sfrutta le iniziative InnerSource. In questo modo, puoi utilizzare in modo efficace la conoscenza e le informazioni interne e sfruttare al massimo la collaborazione con l'AI.

Riferimenti InnerSource

Creare documentazione ricca di contesto

Man mano che lo sviluppo open source matura, emerge la collaborazione tra paesi e fusi orari. Tuttavia, la distanza geografica e le differenze di fuso orario possono rendere a volte difficile la comunicazione sincrona. Ad esempio, il giorno a New York è la notte a Tokyo e non è desiderabile disturbare i contributori con sede in Giappone di notte o interferire con il tempo in famiglia. Pertanto, di solito si preferisce la documentazione basata su documenti scritti. Questo potrebbe essere qualcosa come RFC o documenti di progettazione, o commenti scritti in Issues di GitHub. I documenti formati da commenti in Issues e simili sono anche chiamati documentazione passiva. Questi sono anche forme di documentazione.

C'è una citazione in Understanding the InnerSource Checklist pubblicato da O'Reilly che recita così:

La documentazione passiva è il registro della documentazione che creiamo ogni giorno mentre comunichiamo apertamente. È un ottimo modo per far uscire la conoscenza tribale dai silos e metterla in un formato archiviabile e rintracciabile. Come vantaggio aggiuntivo, è tipicamente conservato con il progetto o il codice che documenta, quindi si trova in una posizione facilmente individuabile e rilevante per il contesto.

Quello che è importante qui è metterlo correttamente in parole, incluso il contesto. È difficile comunicare la comunicazione non verbale, le sfumature e l'atmosfera che sono comunicate attraverso Zoom o conversazioni faccia a faccia asincrone tra fusi orari.

Considera lo sviluppo con l'AI. Ad esempio, GitHub Copilot parteciperà alle riunioni Zoom. Sarà nella stanza del team dicendo: "Ehi, sono GitHub Copilot, facciamo una rapida riunione di controllo". La risposta è no. Tutto il contesto deve essere comunicato all'AI per iscritto. Questo è anche necessario quando si creano documenti appropriati per la comunicazione asincrona, come nello sviluppo open source.

Naturalmente, ci sono differenze nella granularità della documentazione tra lo sviluppo open source e lo sviluppo assistito dall'AI. Scrivere "Voglio risolvere questo bug" in GitHub Issues potrebbe far pensare a qualcuno a una soluzione, ma l'AI non può andare così lontano. Tuttavia, ci sono sicuramente aree in cui l'AI eccelle. Se si vuole esprimere l'architettura cloud come Infrastructure as Code, è meglio scriverla in Mermaid o esprimerla in linguaggio naturale anziché disegnarla in PowerPoint.

Il punto qui non è che tutta la comunicazione deve essere documentata. Tu e il tuo team dovete valutare a che livello lasciare la documentazione, come e dove lasciarla.

AI che coordina la conoscenza organizzativa

Con funzionalità come GitHub Copilot for Docs inclusa in GitHub Copilot X, l'AI può creare la documentazione perfetta per te. I documenti che scrivi possono diventare anche materiali di onboarding per la persona successiva.

In passato, raccogliere informazioni e creare materiali di onboarding per i nuovi ingegneri era un compito comune, ma in futuro, è probabile che l'AI si assuma questo ruolo. Puoi incorporare tutta la conoscenza che possiedi nei documenti come unica fonte affidabile di informazioni.

Questo approccio può essere visto esplicitamente anche nella documentazione di Atlassian. Leggere la loro documentazione tenendo a mente lo sviluppo nativo dell'AI potrebbe portare a nuove scoperte. I documenti che scrivi sembreranno avere una personalità attraverso l'AI. Tuttavia, questo richiede una documentazione sufficiente, come già menzionato.

La distanza tra il linguaggio naturale e l'implementazione diventa più vicina

Come avrai notato, la distanza tra il linguaggio naturale e l'implementazione sta diventando molto più vicina. Come già detto, dal punto di vista educativo, se la scrittura di prompt e codice in un unico posto continua, potrebbe essere possibile creare documentazione in un singolo file. Questo tipo di cambiamento è affascinante.

Checklist

Last updated