Valutare la qualità di un dataset (1/7): Documentazione

Quando si approccia un dataset Open Data la prima cosa che bisogna fare è quella di identificarne immediatamente la qualità: ma come facciamo a comprendere se i dati a nostra disposizione sono “buoni” o meno?

Non esiste un metodo di categorizzazione univoco tale per cui è possibile identificare senza dubbi la qualità di un dataset, esistono però una serie di verifiche che possono aiutare l’utilizzatore finale a comprendere la genuinità di un dataset e, di conseguenza, il suo utilizzo per i propri scopi finali.

Scorporerò la valutazione in 6 post per poter da un lato approfondire maggiormente l’argomento e dall’altro permettere ad ognuno di poter esprimere la propria opinione in merito. Inizieremo oggi con uno degli aspetti che, a mio avviso, è tra i più importanti di un dataset: la documentazione.

Spesso bistrattata perchè ritenuta “poco utile” dal fornitore dei dataset la documentazione è il primo approccio che il consumatore finale di un dataset deve avere: dalla documentazione, infatti, è possibile comprendere le funzionalità e la profondità di un open data e, di conseguenza, la sua utilità per i nostri bisogni.

Ma cosa è, di fatto, la documentazione? Il nome è abbastanza esemplificativo, in sostanza la documentazione non è nient’altro che un testo, solitamente in formato digitale, nel quale vengono illustrate tutte le caratteristiche del dataset open data rilasciato. Partendo dal presupposto che un open data debba essere machine-readable (quindi che sia interpretabile da computer e sistemi automatizzati) la documentazione mi permette di costruire un sistema automatico in grado di interrogare il dataset basandosi sulle specifiche che la documentazione stessa mi illustra.

Come facile immaginare la documentazione aiuta ad accorciare il divide tra il consumatore dell’open data ed il suo fornitore: per quanto non sia obbligatoria la sua presenza fa comprendere fin da subito un approccio customer-friendly (quindi fortemente legato a favorire l’utilizzo del dataset open data da parte del consumatore).

Ma come scrivere una documentazione? Non esiste uno standard definito per la scrittura di una documentazione; si può partire semplicemente dalla pagina doc di github, ad applicativi di terze parti come swagger fino a marketplace che offrono la possibilità di elencare tutti i metodi disponibili per un servizio di API (un esempio è visibile proprio nel progetto startup di cui sono co-fondatore: https://market.mashape.com/sportsop/soccer-sports-open-data)

Avete qualche domanda o qualche dubbio relativo alla documentazione? Sentitevi liberi di lasciare la vostra opinione e/o feedback; solo dalla collaborazione può evolvere l’Open Data.

4 pensieri riguardo “Valutare la qualità di un dataset (1/7): Documentazione

    1. Eccoti un esempio interessante di come fare una documentazione su swagger http://petstore.swagger.io/ Se poi cerchi qualcosa di più specifico si può provare a creare un tutorial o simili.

      Comunque grazie mille del commento: sei il primo su Open Data Italia, ti ricorderemo sempre 🙂

  1. Varrebbe la pena aggiungere che quella del technical writer è una professione e a volte vale la pena consultare qualcuno che è specializzato in questa attività, quantomeno per farsi aiutare nella fase iniziale di un progetto, o per mettere ordine la vasta quantià di documentazione che si accumula in progetti maturi.

    1. Io sono dell’idea che se una persona, sviluppatore o tecnico del dato, debba iniziare un progetto open data ha necessariamente bisogno di una documentazione tecnica.
      Concordo che il tech writer è necessario: a volte sono le classiche mansioni che “tanto poi lo facciamo” mentre invece dovrebbe essere di equa importanza alle altre mansioni.
      Ottima segnalazione Marco.

Lascia un commento