Sempre per quella storia della documentazione


image

Giulio su LinkedIn commenta:

Nella mia esperienza, la documentazione con maggior valore è scritta prima del codice, quella in cui spieghi il contesto di riferimento, l'ambito di applicazione del sistema, l'architettura generale e il Quick start manual. È l'equivalente del TDD, anzi dell'ATDD, ma a livello dell'intero sistema è con la prospettiva di ciascun ruolo: semplice utente, amministratore, manutentore del codice, incluso il marketing. Non deve essere un ritratto, ma uno schizzo che coglie i lineamenti essenziali, che andrà rifinita ad ogni iterazione. Gran parte del suo valore è prospettico: è un esercizio di analisi e comprensione che spesso svela elementi critici del sistema. Se ricordo bene The mythical man month aveva già colto tutto questo diecine di anni fa (purtroppo non posso andare a verificarlo adesso).

Avevo cercato di dire la stessa cosa in precedenza, evidentemente senza lo stesso impatto:

Allo stesso modo trovo molto valore nella documentazione, vi dirò di più trovo molto valore nello scrivere la documentazione. È una forma di testing, spesso ci ritroviamo a scrivere documentazione prima dell’implementazione stessa. L’operazione di scrittura, comprensiva di esempi completi e snippet di codice, impone di mettersi nei panni dall’utilizzatore finale provando in prima persona l’ergonomia di quello che si sta per produrre.

Che va a braccetto con quello che scrive Giulio nel commento:

Nella mia esperienza, la documentazione con maggior valore è scritta prima del codice […] È l'equivalente del TDD […] ma a livello dell'intero sistema è con la prospettiva di ciascun ruolo

Questo per (riba)dire che nella mia esperienza la documentazione serve prima a noi che all’utente finale.

author: Mauro Servienti | posted @ Monday, September 25, 2017 9:20 AM | Feedback (2)

Che l’autunno abbia inizio: #KLab 2017 05 - @klabcommunity


Ebbene si il 22 e non il 21 quest’anno. Per l’ennesima volta ho il piacere e l’onore di partecipare come speaker ad un KLab. Altro trimestre, altro KLab e altra culaccia* ;-)

A questo giro si parlerà di .NET Standard e .NET Core, il sottoscritto si preoccuperà di introdurvi nel mondo magico di .NET Standard, mentre Michael si occuperà del corposo argomento .NET Core (quindi ha diritto a magiare di più).

Maggiori informazioni: http://milestone.topics.it/events/klab-2017-05.html

Iscrizioni: https://www.eventbrite.com/e/klab-5-2017-tickets-37936481036

[*] Sento il profumo solo a scriverlo…

author: Mauro Servienti | posted @ Friday, September 22, 2017 8:55 AM | Feedback (0)

Il lavoratore remoto: la concentrazione e gli spazi


archery-660632_1280

Spesso il lavoratore remoto è anche promotore convinto del lavoro nomade fatto in spazi di co-working o Starbucks e affini. A prescindere dal dove è molto importante che l’ambiente che scegliete per lavorare sia idoneo a voi, non tanto al compito che dovete portare a termine, quanto proprio a voi come persona.

Io non sono animale da co-working, l’ho detto pubblicamente qualche tempo fa:

image

Ma in generale non sono animale da spazi popolati dove conosco le persone. Lo so questa è curiosa: riesco a lavorare seduto per terra in stazione Centrale a Milano ma non in uno spazio comune dove ci sono persone che conosco e magari mi stanno dando fastidio, mentre il fastidio dello sconosciuto riesco a filtrarlo senza problemi.

Quello che è importante realizzare è che lo spazio che scegliamo come nostro posto per lavorare è in funzione di noi e non di quello che stiamo facendo. Ci sono persone che riescono a concentrarsi in mezzo alla folla ma assolutamente non da sole in casa propria (troppe distrazioni note magari), altre che hanno bisogno dell’assoluto silenzio e altre ancora che senza un rave party nelle cuffie non concludono nulla.

Valutate bene che tipologia di persona siete prima di fare la scelta definitiva, non è semplice e all’inizio è difficile capire che magari è proprio la scelta del luogo di lavoro la fonte maggiore di frustrazione.

author: Mauro Servienti | posted @ Tuesday, September 19, 2017 6:26 PM | Feedback (0)

“no documentation”…WAT?


Leggo questo tweet:

image

che rimanda a questo post e sinceramente resto basito (non trovo un altro termine che sia abbastanza politically correct). Davvero c’è gente che comprerebbe un’autovettura di cui nessuno abbia mai testato che gli airbag funzionino o che il serbatoio non prenda fuoco? Oppure c’è gente che si fiderebbe a farsi operare da un chirurgo che ha preso la laurea su Facebook? - oh, wait… ;-)

Potremmo aprire, e mi piacerebbe molto farlo, un dibattito su quale metodologia di test (unit, TDD, test first, acceptance, end-to-end) sia migliore in quale contesto. Ma mai e poi mai mi sognerei di pensare che testare sia totalmente inutile.

Allo stesso modo trovo molto valore nella documentazione, vi dirò di più trovo molto valore nello scrivere la documentazione. È una forma di testing, spesso ci ritroviamo a scrivere documentazione prima dell’implementazione stessa. L’operazione di scrittura, comprensiva di esempi completi e snippet di codice, impone di mettersi nei panni dall’utilizzatore finale provando in prima persona l’ergonomia di quello che si sta per produrre.

Poi…se vogliamo aprire un dibattito sull’utilità di sta roba:

xml-doc

avete vinto facile, non serve a nulla.

In generale penso (pensiamo) che documentare un’API in maniera pappagallesca è decisamente poco utile, farlo in maniera non pappagallesca è pressoché impossibile.

La documentazione che ha valore è ben altra cosa, è anche molto più difficile da scrivere, ma il gioco vale sicuramente ben più di una candela.

author: Mauro Servienti | posted @ Thursday, September 14, 2017 9:24 AM | Feedback (1)

Devops Heroes 2017


Anche quest’anno avrò l’onore e il piacere di essere a Devops Heroes, edizione 2017, nuovamente a Parma, ma stavolta di venerdì. Ci sarà un attesissimo ospite: Martin Woodward, Principal Program Manager per DevOps in Microsoft Corporation ed HP Enterprise.

Io nel mio piccolo mi cimenterò nel raccontarvi come funziona ad oggi il processo di sviluppo, dall’idea al deploy, in Particular.

Dall'idea al deploy: un lungo viaggio che passa per GitFlow e SemVer

Parliamo tanto di DevOps e ci concentriamo sui tool senza soffermarci a pensare che DevOps è principalmente una metodologia. Lo scopo è rendere l'intera filiera il più fluida e lineare possibile, rimuovendo impedimenti e cercando di prevenire e anticipare problemi. Possiamo costruire tutto il processo di sviluppo, partendo dai vagiti iniziali del backlog per finire che il deploy fisico in ottica DevOps? Il processo ha impatto sulle scelte tecniche? Pratiche come SemVer e GitFlow hanno invece un impatto sul backlog? Analizzeremo l'intero processo di sviluppo di Particular Software, dalla gestione del backlog al deploy automatico in produzione, con lo scopo di evidenziare come pratiche che sembrano disconnesse abbiano invece impatto su tutta la filiera.

Maggiori informazioni: http://milestone.topics.it/events/devops-heroes-2017.html

Vi aspettiamo numerosi!

author: Mauro Servienti | posted @ Tuesday, September 12, 2017 9:01 AM | Feedback (0)

Quanto mi piace il nuovo project system di Visual Studio 2017


Visual Studio 2017 introduce un nuovo project system, i famosi file “proj” a cui siamo abituati. Il nuovo modello è obbligatorio per i progetti .NET Core/.NET Standard mentre è opzionale, e purtroppo la conversione è a manina, per tutti (o quasi) i tipi di progetto tradizionali.

Perché mi piace tanto?

Prendiamo come esempio la persistenza di NServiceBus su RavenDB, questa è la diff tra il prima e il dopo: –187 righe. Devo aggiungere altro?

Un’altra cosa che mi piace molto è che potete eliminare il file “packages.config” perché i pacchetti Nuget diventano first class citizen tra le reference del progetto. Inoltre finalmente potete costruire un pacchetto Nuget direttamente in fase di build senza pressoché fare nulla. Finalmente tutti i file presenti in una directory sono inclusi per definizione in un progetto, portando praticamente a zero le merge e le rogne in fase di evoluzione massiccia di un progetto.

Ultima cosa che trovo fantastica è che potete esternalizzare in file “Directory.*.proj” parti di configurazione che sono comuni a più progetti che vivono nella stessa folder, o solution. Mi piace poco invece la sintassi usata per escludere contenuti, me ne farò una ragione, anche se è veramente triste.

Provatelo ne vale la pena, vale anche la pena investire tempo per convertire progetti esistenti perché non siete obbligati a passare a .NET Core, l’unico vincolo è Visual Studio 2017.

author: Mauro Servienti | posted @ Tuesday, August 22, 2017 5:16 PM | Feedback (0)

Basta! basta! basta! pensare alla soluzione non serve se non si è compreso il problema.


Nota per il lettore:

Questa (mini) serie di post non è una ricetta per trasformare un’organizzazione in un ambiente in cui fallire non sia un problema, mi spiace dirvelo: non esistono ricette o il manuale delle istruzioni. Quello di cui parlo in questi 6 post sono le cose principali che sono emerse nel lungo processo di trasformazione, iniziato ormai 3 anni fa, che hanno portato Particular Software ad essere quello che è oggi.

La vostra ricetta la potete trovare solo voi facendo quello che forse è il primo, e più difficile, passo: chiedendo a voi stessi, ai colleghi e ai dipendenti che cosa non va bene e come lo cambierebbero. Ovviamente dovete ascoltare le risposte, criticarle e poi infine dovete voler cambiare.

376102567_46d54e403f_b

Mi è capitato spesso di assistere a situazioni in cui ci fossero forti pressioni “dall’alto” perché un problema venisse risolto  e venisse risolto alla svelta. Il team si dannava, faceva le notti, accumulava frustrazione, per poi scoprire che la soluzione implementata non era quella desiderata.

L’inghippo, se di inghippo e non di miopia si può parlare, è abbastanza semplice: La fretta genera l’errore in ogni cosa.

Qualcuno, spesso qualcuno in alto nella gerarchia e guarda caso anche molto distaccato dal mondo reale, lamenta un problema e data la sua posizione di potere ne pretende la soluzione. Nella catena di schiavi nessuno ha il coraggio, se lo sa, di dirgli che quello non è il vero problema ma è solo il sintomo. E il team si ritrova a fare le notti.

In retrospettiva posso dire che noi spendiamo tantissimo tempo, dato un presunto problema, per comprendere a fondo se quello è veramente il problema da risolvere o se invece è solo un sintomo.

Identificare il vero problema da risolvere innesca due cose interessanti:

  • Molte meno discussioni interne perché una volta identificato il problema vero siamo tutti orientati nella stessa direzione; tant’è che uno dei metri di misura che ci fanno dire “forse è il problema sbagliato” è quando il dibattimento sulle soluzioni si trascina, e spesso le soluzioni proposte sono diametralmente opposte.
  • La soluzione si rivela essere una soluzione di (più) lunga durata e questo gratifica, con tutto quello che ne consegue.

Prima di iniziare a pensare ad una soluzione concentratevi sul problema.

Post in questa (mini) serie:

author: Mauro Servienti | posted @ Thursday, August 17, 2017 8:01 AM | Feedback (0)

Windows 10 - Controlled Folder Access


controlled-folder-access

Una* delle macchine che uso quotidianamente per lavoro è nel programma insider, slow ring, e da un po’ è stata aggiornata a Creators Update. Una delle feature che aspettavo era il “Controlled Folder Access”.

Quello che potete fare è definire una o più cartelle (e di conseguenza le relative sotto-cartelle) come “controllate”. Questo fa si che fondamentalmente solo i programmi autorizzati possono apportare modifiche a quelle cartelle. Ovviamente la cosa che salta subito all’occhio è che un ransomware non risulta tra i programmi autorizzati e quindi problema risolto.

Occhio perché al momento non è tutto oro quel che luccica

La cosa funziona e funziona bene. Microsoft dichiara, nella UI di Defender, che Windows contiene una lista di applicazioni note che sono autorizzate a prescindere. Ad esempio sulla mia macchina Visual Studio Code fa tutto quello che deve fare senza problemi, Excel no, Word si. Misteri della fede e delle versioni insider, quindi non è che mi possa lamentare.

Ma non è questo il problema. La cosa noiosa è che le applicazioni si comportano in maniera alquanto strana, rendendo difficile anche per l’utente esperto capire, cosa sta succedendo.

Excel, ad esempio, apre i file senza problemi ma poi fallisce miseramente con un errore totalmente scorrelato al momento del salvataggio. Il problema di fondo è che Excel non essendo tra le applicazioni autorizzate sulla mia macchina, non riesce a creare il file temporaneo necessario per gestire le modifiche e quindi in seguito non riuscirà a salvare.

Non ho fatto esperimenti, ma presumo che il sistema operativo rimbalzi l’applicazione con un errore ben preciso, che al momento l’applicazione semplicemente non sa gestire. Nel mio piccolo mi ero dimenticato di averle attivate e quindi ci ho messo un po’ a capire cosa stava succedendo.

L’altra cosa ad oggi noiosa è che non è sempre facile capire quale sia l’eseguibile che dovete autorizzare, se usate molti tool da command line succede che voi interagite con xyz.exe che a sua volta invoca un altro eseguibile che viene bloccato da Defender, generando il perfetto yak shaving.

* Una sola perché fidarsi è bene, ma… devo lavorare :-)

author: Mauro Servienti | posted @ Tuesday, August 15, 2017 10:20 AM | Feedback (0)

I “virgoletti” di WhatsApp…


…ci seppelliranno. Avete anche voi amici e/o parenti che sono ossessionati dai “virgoletti”, così li ho sentiti chiamare, di WhatsApp?

Per uno che la prima cosa che fa è disabilitare tutte le notifiche, compresi i virgoletti maledetti, e se non può disabilitarle rimuove l’app, capirete che è incomprensibile. Quello che mi meraviglia di più è che tutta questa gente è spesso nata in un tempo in cui non esistevano neanche i cellulari e se avevi bisogno di qualcuno o di qualcosa la cabina telefonica e il gettone erano il massimo che potevi desiderare. Se non ti rispondeva nessuno te ne facevi una ragione e andavi avanti. Oggi come oggi ci sono coppie che scoppiano o amicizie che vanno in frantumi perché le “virgolette blu”.

Sinceramente non ho parole, se non: provate ad essere irreperibili e felici. È agosto, fa caldo, tra qualche giorno torno a parlare di cose normali e la pianto con gli sproloqui ;-)

author: Mauro Servienti | posted @ Monday, August 14, 2017 7:45 AM | Feedback (1)

Ipocrisia 2.0


image

Lo lascio qui, così come riflessione.

  • Capezzoli no, razzisti si
  • Capezzoli no, nazifascisti si
  • Capezzoli no, Salvini si (è una specie speciale dei due punti precedenti)
  • Capezzoli no, fakenews come se non ci fosse un domani

Marchino Zuckerbino…sei ridicolo e anche un po’ bigotto.

author: Mauro Servienti | posted @ Tuesday, August 8, 2017 7:02 AM | Feedback (0)