 Anche lui è membro della Comunità di Wolpestra 2010, quindi da tantissimo tempo, più o meno. Cercherò di essere breve, lo sto già mettendo in difficoltà perché sono interista, questa cosa. Mi ha fatto capire che gli dà molto stridio, quindi cercherò di limitare i danni. E oggi ci parlerà di l'importanza di documentare il proprio lavoro. E fate un applauso e ricoso il scenario. Andiamo velocemente, cercherò di convincere anche più scelte ci oggi, di come sia importante documentare nello sviluppo di progetti software. Esistono due tipi di documentazione essenzialmente per sviluppatori e per utenti finali, cioè quelli che useranno il software. Sono due documentazioni completamente differenti che richiedono anche competenze differenti. Quindi anche chi farà documentazione per sviluppatori, per sviluppatori e utenti finali probabilmente non saranno le stesse persone. La documentazione per sviluppatori. La documentazione per sviluppatori è una parola che in cute ti more. Se non ti more comunque provoca un senso di nausea, un senso di disagio. Gli sviluppatori hanno un grosso difetto a volte, riscrivono codice e magari credono anche di farlo il meglio di altri. Però come tutti gli esseri umani hanno dei piccoli momenti di lucidità nei quali realizzano che non vogliono farsi sempre del male. Allora vanno a cercare su Google per vedere se trovano un qualcosa o su GitHub un qualcosa che possa fare al suo caso. Suponiamo ad esempio Mario, un tantomatico sviluppatore. Niente, non so se qualcuno si chiama Mario, ma niente contro. Che stia proprio attraversando questo momento di lucidità. Prende, va su GitHub, vedi un nostro progetto, dici ha bello, c'è un piaccio, c'è anche un esempio live, decide di integrarlo. Si accorge però, ritornando su GitHub, che non abbiamo scritto documentazione. È uno sviluppatore, non si abbatte e va a vedere nel codice. Ma anche lì vede che non c'è poco. Quel punto cosa fa? Dice pensa che si deve fare versus engineering se lo riscrive da zero, la frittata è fatta. Noi abbiamo perso un nuovo utente, un contributor probabile. Probabilmente abbiamo acquisito un nuovo competitor, perché se Mario va a mettere questo codice su GitHub, sarà il nostro competitor. E quindi di fatto per Mario il nostro codice non è mai esistito. Allora cosa dobbiamo fare? Dobbiamo cercare nel nostro progetto di creare documentazione in tutta una serie di modalità. La cosa più semplice è la documentazione in line tramite commenti o doc block, che sono opportuni commenti fatti in un certo modo. Fino a scrivere API reference e sportiamo delle funzioni allegando documenti sull'architettura, il changelog, il rhythmic nel caso di plugin fondamentale. Fino a dare esempi di codice, una guida per contributors, articoli e che più ne ha. Certo che costa fare codice. Allora vi voglio dare una scorciatoia che ovviamente non è questa, perché non basta scrivere codice perfetto, perché si basa su due pros e posti essenzialmente sbagliati, che effettivamente sia un bel codice. E che l'utente finale che poi lo andrà a utilizzare abbia le stesse nostre skill e riesca a comprendere quello che abbiamo fatto. Quello che possiamo fare è dotare i codi standard, codi standard nella scrittura del codice, che sono una serie di linee, guida, di direttive e di aspettative che ci guidano nella scrittura di un codice. Questi codi standard vanno dall'ostile del codice, dalle best practice, dal naming dei file, dall'organizzazione, anche dei file, naming delle variabili e classi, ovviamente nella documentazione l'ha anche deve essere scritta in un certo modo. Qui ho messo un link su quelli che sono i codi standard relativamente al mondo Warpless. Brevemente un esempio, non so se vedete per faccelo stare, di un codice preso dalla codebase Warpless, una funzione piazzata lì senza codi standard. Già la stessa formatazione con gli spazi, indentature eccetera lo rende molto più legibile. Ovviamente se a questo ci aggiungiamo codice, doc block eccetera, vedete come anche in assenza di una documentazione più completa uno sviluppatore riesca, guardando questo codice, a capire e usare questa funzione all'interno dei propri progetti. Lo stesso di Cassi per il JavaScript, esistono sempre. Abbiamo visto velocemente cosa sono i doc block. Doc block sono dei commenti scritti, non necessariamente multilinia, scritti in un opportuno modo, che hanno all'interno anche di tag, che sono identificati dal carattere, che ci danno ulteriori informazioni sulla funzione, sul codice che stiamo scrivendo. Quindi ci dicono la tipologia dei parametri, piuttosto che i parametri ingresso, i parametri in uscita e hanno anche una loro descrizione. Questo vale sia per la funzione, per i filti, nel caso di warps, hook e quant'altro. Questi doc block possono essere usati tramite software di generazione automatica di documentazione per generare una documentazione, quella che viene detta le piae reference, del nostro codice che può essere direttamente pubblicata sul nostro sito e anche nel caso di PCP documentor, anche ricercabile. I più avanzatide hanno un supporto di doc block e li utilizzano per aiutarsi della scrittura del codice. Quindi via via che scriviamo, ci danno indicazioni sugli parametri ingresso, una breve descrizione, quindi ci supportano. Ovviamente il doc block facendo parte la documentazione dei code standard, i code sniffer, che sono degli, diciamo, nezzattori statici di codice, ci possono dare una mano corregendo quelle che sono le lori sintatici dei doc block. Quindi documentare è importante. Come avete visto, migliora la legibilità. L'hanno un'autonomilità e ci fa risparmare tempo, che è denaro, immaginiamo di dover ritornare sul nostro codice, fatto anche magari un mese fa non documentato, magari facciamo fatica, non solo noi, ma anche i nostri colleghi di un team. Averlo documentato aiuta sicuramente l'integrazione e la modifica e non solo anche può aiutare, diciamo, il suo utilizzo anche da parte di terzi, nel momento in cui noi questo progetto lo vogliamo condividere. In generale aumenta la qualità del codice. Qui sotto c'è un link riferimento a quelli che sono i codi standard del codi in line. Brevemente in changelog, ma qui facciamo veloce, io lo ritengo molto importante, mantenere sempre aggiornato in un file opportunamente formatato con degli standard opportuni, ci dà subito allo sviluppatore una visione di quelle che sono le modifiche salienti dell'ultima risa del codice, cose che potrebbe fare guardando il codice, ma qui ovviamente è una cosa molto più veloce. Passiamo alla documentazione per utente finale, che è quella più corposa ovviamente, a volte anche la più trascurata per progetti che magari non devono essere esportati per progetti interni. Come abbiamo detto, richiede competenze diverse e probabilmente non viene fatta dallo stesso developer che ha sviluppato il progetto. Come vedete, ci sono un sacco di punti che abbraccano la documentazione per utente finale. Da un semplice elenco dei requisiti ha un setup a configurazione, vi avvia un glossario al menù di aiuto di Warpers nel caso noi facciamo contestuali. In caso fosse un plugin o un tema Warpers è possibile aggiungerli. Fino via scrivere una guida anche risoluzione di problemi, screencast, quindi video, tutorial, articole e quant'altro. La documentazione per utente finale è un'arte, perché richiede non solo competenze scientifiche, ma chi scrive documentazione per utente finale deve avere anche competenze umanistiche, perché io non sono sviluppatore, faccio anche documentazione per utente finale, ma cerco di farla, cercando il più possibile di... veramente un piccolo elenco di punti che secondo me sono importanti da tenere in considerazione nella scrittura di una documentazione per utente finale. In genere la mettiamo su web, comunque su media online. La prima cosa che deve essere comunque cessibile, quindi deve rispettare le stesse, diciamo, accortezze di accessibilità di un sito web. E' importante secondo me essere anche corrente nella formatazione, quindi avere subito... dare subito l'utente inizialmente un'indicazione su quelle che saranno, diciamo, le convention, diciamo, di formatazione, quindi il cursivo lo utilizzerò per una serie di informazioni, il grassetto piuttosto che evidenziare con certe icone determinate informazioni, etc. Ovviamente, se nel caso volessimo introdurre anche esempi di codice, evidenziare bene il codice che raramente, per l'utente finale, si mette il codice comunque a evidenziarlo bene, darò link ai forum di supporto, se lo abbiamo, perché è una preziosissima fonte di informazioni, di risoluzioni e problemi, e testarla. Anche se non esistono, diciamo, strumenti di unit test per la documentazione di l'utente finale, lo dobbiamo testare a meno che chat GPT non venga fuori, che con uno strumento che ce la faccia, ce la crea in automatico dal progetto, e, a di là dei corretori sintattici, testiamola, corregiamola, rilegiamola, facciamo aiutare anche da amici colleghi, oppure se abbiamo un progetto anche commerciale, individiamo una fetta di beta tester a guidare questa documentazione. Lo dobbiamo mantenere la giornata. Il markdown è quel formato che io utilizzo personalmente per scrivere la documentazione, perché è un formato molto semplice che ha pochi tag ed è molto portabile. Tra l'altro è il pub di WordPress, molti contenuti che utilizzano proprio il markdown per contenere una documentazione. Concludo, accennando a quello che ho scritto Vark, che è un acronimo che sta per visual, oral, read-write, kinestetic, praticamente è una teoria molto interessante, il mio avviso, che sui listi di apprendimento, insolventi ci dice che le persone apprendono in quattro modalità, facendo, ascoltando, leggendo e facendo. Non tutti abbiamo un'unica modalità, quindi siamo molti modali, quindi il consiglio è di inserire nella vostra documentazione l'utente finale tutta una serie di elementi che vanno dai video, dai podcast, piuttosto dai esercizi e ovviamente la scrittura è di farciare un numero maggiore di utenti nella nostra documentazione. Io concluso, quindi la documentazione, come avete capito, è come il codice, Cuba almeno un 30% assieme allo sviluppo analisi e al test, non diamo mai più scontatto che sia conclusa, una volta scritta, perché come il codice va sempre ottimizzato, curato, eccetera, e soprattutto all'aggiornamento del codice aggiorniamo la documentazione anche per l'utente finale, una documentazione absoleta da l'impressione di un codice absoleto. Io ho finito Nel frattempo, Mario ha visto un altro mio progetto, documentato e ha fatto un appurri, è diventato un nuovo contributore.