Come abbiamo creato un «Read the Docs» per pubblicare documenti pubblici su Docs Italia

Questa storia nasce dal Team Trasformazione Digitale dell’AgID che inizia a pubblicare documentazione della Pubblica Amministrazione su un formato online nuovo che si chiama Read the Docs.

Read the Docs (RTD) è un formato che permette di leggere testo su dispositivi mobili adattandosi alle dimensioni del display e consente di cercare parole nel testo attraverso uno spazio apposito. Già solo queste due caratteristiche lo fanno preferire al classico formato PDF usato per la maggiore nei siti web della PA. Purtroppo il PDF non si adatta ai dispositivi mobili e non consente un agevole ricerca di testo al suo interno.

Per arrivare alla pubblicazione di documenti su RTD è necessario compilare file nel linguaggio RST (reStructruredText) e renderli disponibili in progetti dentro il repository di Github.

Dopo che il Team Trasformazione Digitale inizia la pubblicazione di documenti della PA su RTD, alcuni dipendenti di PA cominciamo a pubblicare documenti pubblici su questo formato  e il risultato è senza dubbio molto gradevole e comodo ai fini della lettura su ogni dimensione di schermo.

Come ogni fenomeno nuovo c’è sempre l’aspetto e il ruolo pionieristico che è importante per fare da traino per gli altri. Ed è così che ci ritroviamo Ciro Spataro (Comune di Palermo) e Pablo Persico (Città Metropolitana di Napoli) a scambiarci idee e proposte per pubblicare documenti pubblici su Read the Docs, e fra un messaggio e un altro arriviamo alla conclusione condivisa che sarebbe utile e bello costruire un tutorial sulle modalità di costruzione di un documento da pubblicare Read the Docs: da dove partire e tutte le procedure da seguire. Cominciamo a lavorarci condividendo un Google doc all’inizio, e strutturiamo didatticamente il tutorial in 2 parti: una in cui si spiega una procedura per chi non è molto addentro alle procedure di compilazione e versionamento dei documenti e una per i più esperti. Questo al fine di arrivare ad ogni tipologia di dipendente pubblico in fatto di competenze digitali.

All’iniziativa prende parte Andrea Borruso per la supervisione dell’intero lavoro didattico, vista la sua attitudine e piacere a “spiegare bene” le cose.

Quello che ci ha preso maggiormente in questa iniziativa è stata la voglia di vedere i documenti della Pubblica Amministrazione visualizzati come mai ad oggi è stato fatto. Una sorta di vendetta contro un PDF scomodo 😉

Dal Read the Docs creato è possibile ottenere, automaticamente dalla stessa piattaforma, il documento in formato PDFEPUB ed HTML (zippato). Quindi per coloro che non possono rinunciare al PDF non c’è la possibilità di alcun trauma psicologico.

Il resto lo potete leggere nel Read the Docs http://come-creare-guida.readthedocs.io

 

Collezioniamo tutorial per la condivisione della conoscenza

La serie televisiva di “Sanford & son” del secolo scorso è stata un ispirazione per l’attività di collezionamento di risorse, che sto per esporre.

Cercare risorse o informazioni sul web per imparare a fare qualcosa di nuovo, e trovarle, non basta, se poi rimangono nel caos del “Google search”. Come faccio a ritrovarle di nuovo se le ricerco? Devo ritornare nel Google search e non ricordo a quale pagina mi vengono presentate. Nel frattempo perdo tempo (sfogliare le pagine di risposte che mi fornisce Google).

Petrusino, da un paio di anni, è un catalogo online che elenca mappe e infografiche sulla Sicilia, … ora è il tempo di catalogare i link dei tutorial creati da qualcuno che ha investito ore per scrivere (e condividere) come si costruisce qualcosa che ha attinenza con i dati ed la cultura digitale.

Tutorialteca

I tutorial oggi rappresentano una preziosissima fonte di conoscenza condivisa, formazione informale. Mi è capitato personalmente di acquisire competenze digitali leggendo tutorial di altre persone e quindi ho capito che è importante valorizzarli al meglio. Da questa consapevolezza nasce un idea semplice: collezionare i tutorial che veicolano la cultura digitale e sui dati. Creare una sorta di “tutorialteca”.

Petrusino ha fatto da apripista, con la sua interfaccia pulita, semplice e con un efficiente motore di ricerca interno delle risorse catalogate. Ormai è un hub di conoscenza tematica utilizzato sia da pubbliche amministrazioni che da cittadini e professionisti, e le risorse censite (praticamente dei link) non sono così facilmente individuabili dall’ormai epico Google search. Fate prove cercando su Petrusino e su Google!

ACCUSSI’

Con Andrea Borruso ne parlammo tempo fa di creare un catalogo dei tutorial. Da qualche giorno — insieme a Giuseppe Ragusa — ci siamo messi all’opera per riusare l’interfaccia grafica di Petrusino. Abbiamo clonato il codice su Github per un nuovo progetto al quale abbiamo dato il nome di Accussì. In siciliano “Accussì” significa: “così, in questo modo” e gli autori dei tutorial in fondo fanno questo: ci indicano un po’ come fare le cose.

Oggi c’è la disponibilità pubblica di questo catalogo interrogabile su parole chiave, su autore e su tag. Abbiamo previsto una pagina “proponi” al fine di raccogliere facilmente quanto più tutorial possibili. Chiunque abbia costruito un tutorial sull’uso dei dati, su come si fa una mappa, un infografica, una trasformazione di file in formati diversi (da pdf a csv per es.), e su cultura digitale in generale, può censirlo in questa pagina, arricchendo il catalogo, che diventa, così, un patrimonio di conoscenza comune.

database su GoogleDrive che alimenta Accussì

Come è fatto?

Gli strumenti principali usati per realizzare il catalogo Accussì sono 4:

  • Simile Exhibit, per realizzare il cuore di Accussì, ovvero l’interfaccia di navigazione del catalogo;
  • Twitter Boostrap, per dare un po’ di stile alle pagine pubblicate;
  • GoogleDrive Sheet, per raccogliere e distribuire i dati che fanno da database sorgente;
  • GitHub Pages, per l’hosting dei file che costituiscono Accussì.

Il Codice

Il codice di Accussì, che si può clonare e adattare ai vari scopi, è disponibile in questo repository GitHub: https://github.com/SiciliaHub/accussi/.

Un nuovo servizio  di opendatasicilia

accussi.opendatasicilia.it lo trovate come nuovo servizio all’interno di “Cose nostre” di opendatasicilia.it, assieme alle altre cose già realizzate.

A noi piace fare queste cose, e speriamo che la nuova “tutorialteca” sia di ampia utilità.

Lunga vita a Sanford & son, ai costruttori di tutorial e a opendatasicilia.


immagini

  • la foto di Sanford & son è rilasciata con lic CCO
  • l’immagine Tutorial di Nick Youngson è rilasciata con lic. CC BY SA 3.0
  • le altre immagini sono screenshoot degli strumenti usati per costruire Accussì