Con tutti i blog tecnici che ci sono in giro (compresi quelli di sviluppatori e program manager Microsoft) il ruolo della documentazione tecnica è molto cambiato. Il pattern più comunemente usato a fronte di un problema (di natura spiccatamente software) è “vado su Google e digito più o meno il testo della domanda che farei a chi di dovere se solo sapessi chi è”. E per la cronaca, una volta quello di dovere ero spesso proprio io!  

La cosa bella è che sempre più spesso la risposta che si cerca, ebbene, la si trova. C’è sempre qualcuno nel mare infinito della blogosfera che ha già passato gli stessi guai nostri e, bontà sua, ha pensato di farne un post. Talvolta capita che sia più per logorrea internettica che per effettivo senso di community ma tant’è: il risultato non cambia e per quanto astruso e non-documentato possa essere il metodo di cui si vuol sapere di più, c’è sempre qualcuno nel mare magnum di Internet che lo sa.

Ma allora basta IntelliSense!

Mi serve ancora la documentazione tecnica?  Lo scorso anno a BASTA! Italia ricordo di aver chiesto al buon Ted Neward il suo punto di vista sullo stato di salute della documentazione tecnica di corredo ad API e framework. Alla fine concordammo sul fatto che tanto il mondo va così e che ci piacerebbe tanto che la documentazione comunque ci dicesse tutto in modo chiaro e preciso. Perché per quanto leggibile e dotato di unit-test adeguati in qualità e quantità il codice non si auto-documenta.

Facciamo un ragionamento breve e semi-serio. Se avessimo una documentazione tecnica puntuale e precisa allora non ci sarebbero tanti blog tecnici. Di cosa scriverebbero? Dell’ovvio? Suvvia! Di conseguenza tutti i potenziali blogger se ne dispiacerebbero e darebbero la colpa a Microsoft. Per evitare ciò, allora, Microsoft per amore di community decide di risparmiare sulla documentazione e si limita a documentare funzioni e proprietà di milioni di classi con la stessa stringhettina che appare in IntelliSense e nei commenti XML del sorgente.

I blogger sono contenti perché possono scoprire comportamenti indesiderati, anche se abbondantemente previsti dalla logica del metodo. Tutto ciò che non è scritto nella documentazione di fatto non esiste e se accade è un effetto indesiderato di cui ha senso bloggare.

C’era una volta una utilissima sezione Remark nella documentazione di ogni classe .NET o funzione del Windows SDK. Se ne contano sempre meno, ma il punto è che senza una sezione Remark che commenta e spiega la logica di un metodo, la documentazione non serve: basta IntelliSense.

La colpa è dei blog? Chissà. Ma sono nati prima i blog o la documentazione scheletrica modello HelloWorld (o HelloWin)? Sono i blog (e il loro uso) che hanno portato al progressivo impoverimento della documentazione o è invece il contrario?

Secondo me, è la prima che ho scritto. Ma all’atto pratico cambierebbe poco anche se fosse la seconda.

Libri & Co.

E dei libri vogliamo parlare? Qui sono chiaramente parte in causa ma c’è qualcosa che posso dire per averla provata sulla pellaccia. In tutta sincerità temevo un crollo delle entrate da royalties nell’annus horribilis 2009. Che non c’è stato. Non che sia andata meglio del 2008 e anni precedenti, ma pesando il dato sulla quantità e peso specifico dei libri in vendita è un successo.

Significa qualcosa?

Significa sicuramente che va cambiato il focus dei libri—di tutti i libri tecnici. Il focus, se non proprio gli argomenti. Il libro scritto a quattro mani con Andrea Saltarello “Microsoft .NET: Architecting Applications for the Enterprise” ha un indice di gradimento quasi mai visto prima (e non sto parlando delle recensioni su Amazon, ma di un indice usato internamente alle case editrici per valutare il gradimento di un prodotto). 

Significa probabilmente che in conseguenza dei blog un lettore può trovare facilmente una risposta semplice andando su Bing o Google. Ma quando la risposta comincia con “Beh  dipende”, o la domanda stessa è difficileda articolare perché risulti comprensibile a un motore di ricerca, beh allora un buon libro ha un senso. Ma si tratta di libri diversi da quelli scritti finora.

Oggi come oggi per avere una sana ed efficace Information Technology, bisogna ripartire da una sana ed efficace information sulla technology. Basta con le liste di metodi e argomenti e avanti con il funzionamento delle cose, gli scenari possibili, le architetture desiderabili. Non si deve certo arrivare a disdegnare la tecnologia nuda e cruda, ma non deve essere la tecnologia a guidare un libro o un corso. ASP.NET non significa nulla se non lo si aggancia ad una discussione su principi SOLID e architetture layered. AJAX è pura fuffa se non lo si aggancia ad uno use-case preciso in cui si stabilisce cosa serve realmente all’utente che vada ottenuto in modo asincrono.  

La blogosfera ci ha permeati tutti ed è francamente un mare in cui è dolce un po’ per tutti naufragare. Ma essendoci dentro perdiamo di vista ciò che ci circonda e ci serve una guida. La documentazione tecnica (help, libri, corsi) può farlo, ma deve tornare ad essere materia di discussione sui massimi sistemi, non sui minimi overload.