docs.microsoft.com: un punto di accesso unico per tutta la documentazione tecnica Microsoft

Se state utilizzando prodotti e servizi Microsoft, vi sarà capitato sicuramente di approdare sul “nuovo” sito di Microsoft dedicato alla documentazione: http://docs.microsoft.com.

Una delle più grandi novità di questo nuovo modo di produrre la documentazione, non è tanto l’aver raccolto sotto un unico dominio tutto quanto, ma il fatto di essere stata prodotta (almeno in parte) dalla community.
Questo è possibile grazie al fatto che la documentazione è opensource e accessibile a tutti.
Infatti ogni prodotto o tecnologia ha il suo repository Github di riferimento in cui ogni utente può richiedere di effettuare una modifica o dare un feedback direttamente.

Proviamo a vedere nel dettaglio come funziona.

Come effettuare una modifica

Accendendo al portale http://docs.microsoft.com selezionate la tecnologia di cui vi interessa visualizzare la documentazione.
Io ad esempio, per deformazione professionale, seleziono “ASP.NET”.

Una volta aperto un articolo, in alto a destra avrete sempre presenti alcuni pulsanti: Feedback, Edit, Share.

Cliccando su Feedback, verrete rimandati in fondo alla pagina in cui è presente un box (se siete loggati su Github) in cui è possibile lasciare un feeback sulla pagina che state attualmente leggendo.
In questo caso è buona norma essere più precisi possibile, soprattutto in caso stiate segnalando una errore o un refuso all’interno della pagina o del codice.

Cliccando invece sul pulsante in alto Edit, il browser farà un redirect direttamente sulla pagina di Github in cui è presente il sorgente della pagina.
A questo punto, senza nemmeno aver bisogno di scaricare i sorgenti in locale, potete cliccare sull’icona di modifica (la classica immagine con la matita) in alto a sinistra, per iniziare a modificare l’articolo.
Github creerà un fork del repository appena avrete finito le modifiche e cliccherete sul pulsante Propose file change situato in fondo alla pagina.

Non vi resta che aspettare che il responsabile del repository della documentazione decida di accettare la vostra modifica o la respinga con una motivazione.

Dare un Feeback al prodotto

Cliccando sempre in alto alla pagina sul pulsante di Feedback, potete lasciare un riscontro direttamente sul prodotto in generale.
Se cliccate infatti sul pulsante Product Feedback verrete rimandati alla pagina di default del repository di Github di riferimento.
Questo avviene per la maggior parte dei casi perchè, ad esempio, nella documentazione di Azure si viene rimandati a un portale specifico per i feedback (per esempio Azure) e per altri ancora direttamente sul portale di UserVoice.

La cosa importante da sapere è che comunque quel link vi rimanda nel giusto posto per effettuare il feedback, senza dovervelo andare a cercare in giro.

Nel caso che i feeback vengano raccolti su Github, nella pagina in cui venire indirizzati ci sono le istruzioni per dare il contributo in maniera corretta, per facilitare il lavoro del team che lavorerà sulla vostra Issue.
I feedback raccolti in questo modo, saranno appunto delle issues direttamente sul repository di Github.

Se navigate nella sezione Wiki del repository di Github, trovate comunque tutti i riferimenti necessari per poter eseguire il contributo nel migliore dei modi.
Potete trovare, ad esempio, il template con cui compilare la issue per poter standardizzare più possibile la vostra richiesta.

Devo dire che in questo modo è molto migliorato il modo in cui possiamo interagire con la documentazione perchè, rispetto a prima, non siamo semplici fruitori ma possiamo modificarla e migliorarla per le altre persone che la leggeranno in futuro, con un perfetto spirito community.