Note di redazione
Questa pagina di note è a cura dell’associazione onData, non è parte delle linee guida ufficiali dell’Agenzia per l’Italia Digitale (AgID).
Introduzione
Per noi dell’associazione onData tutti i documenti pubblici di riferimento - come queste linee guida - dovrebbero essere resi disponibili in lettura anche su Docs Italia.
Per tante ragioni:
- permette un processo collaborativo di pubblicazione e modifica, in cui chiunque può proporre contributi e suggerimenti;
- è un punto unico di riferimento che offre una visione d’insieme su questi documenti pubblici;
- i documenti evolvono nel tempo e su Docs Italia è possibile seguirne lo sviluppo;
- i documenti pubblicati su Docs Italia hanno un indice ben strutturato, un motore di ricerca efficace e sono facilmente leggibili, anche da smartphone.
Limitarsi a pubblicare solo file PDF non consente di sfruttare tutte queste opportunità.
Qui facciamo riferimento alla versione finale del documento pubblicato da AgID. Infatti ne esiste una versione precedente in bozza su Docs Italia, ma non è aggiornata ai contenuti correnti (non contiene ad esempio il frutto del ricco iter partecipativo di modifica).
Con un PDF è molto scomodo fare anche il passaparola e inviare ad esempio in chat, in un’e-mail, in una condivisione su un social network, ecc. il link a uno dei requisiti delle linee guida. Per queste ci sarebbero da sfogliare 150 pagine di PDF, fare una ricerca di testo, e magari in un terminale mobile scomodo (per un PDF).
Mentre con questa versione HTML, si può copiare il link al requisito 2 e scrivere in chat:
Guarda che bello, il requisito 2 delle linee guida open data dice che i dati devono essere pubblicati in formato CSV, non quell’orrendo PDF https://ondata.github.io/linee-guida-opendata/capitolo-4.html#req-2
E chi lo riceve visualizzerà subito il requisito 2 nel suo contesto, come in Figura 1, e potrà approfondire la lettura.
Un altro elemento che ci ha spinto a creare questa versione alternativa a quella ufficiale è una cosa vecchia come il web: la navigazione ipertestuale.
Queste linee guida sono ricche di richiami a fonti esterne, come i link agli articoli del Decreto Legislativo di riferimento per queste linee guida. E sarebbe prezioso avere il link ipertestuale agli articoli citati.
Questo (molto spesso) non avviene nel documento ufficiale e non è un aspetto che dipende dal formato PDF.
Sotto un esempio dell’inizio del capitolo 4. Nella prima immagine il documento ufficiale in cui non c’è alcun link ipertestuale agli articoli citati, mentre nella seconda immagine (relativa a questo progetto) ci sono quelli per i citati articoli 6, 9-bis e 12-bis del “Decreto Legislativo 24 gennaio 2006, n. 36”.
Come abbiamo lavorato
Abbiamo iniziato provando a trasformare il documento PDF ufficiale in un formato testuale, adatto poi a essere trasformato in HTML. Ma per la “ricchezza” in termini di struttura e contenuti, non riuscivamo a ottenere un risultato soddisfacente.
Abbiamo allora chiesto ad AgID di inviarci il documento nel formato in cui nativamente è stato redatto (il PDF è infatti qui un formato di esportazione).
Ci hanno allora inviato il file LG-Open-Data_v.1.0.docx, ovvero il documento in formato Microsoft Word.
Lo abbiamo convertito in un formato testuale più adatto a essere trasformato in HTML, ovvero in Markdown (.md), utilizzando Pandoc.
A partire da questo formato, abbiamo creato un progetto Quarto e lo abbiamo esportato in HTML.
Modifiche al documento originale
Abbiamo apportato pochissime modifiche al documento originale, per renderlo più leggibile e navigabile. Ma nessuna alterazione del contenuto o di significato:
- abbiamo aggiunto alcuni collegamenti ipertestuali;
- abbiamo corretto alcuni collegamenti ipertestuali non più funzionanti;
- abbiamo trasformato la “check list” utile alla verifica di alcuni aspetti giuridici, presente nel capitolo 5, da tabella a elenco puntato gerarchico (ci sembra più leggibile sul web);
- abbiamo suddiviso la tabella presente nel capitolo sulle categorie tematiche dei dati di elevato valore, in più tabelle.
Potremmo aver commesso degli errori, per cui ti chiediamo eventualmente di segnalarceli.
Il codice sorgente di questa versione
Il codice sorgente di questa versione HTML delle linee guida è pubblicato su GitHub.
Nostre note dentro il testo
Le inseriremo solo se necessario, per chiarire o approfondire un concetto. In due modi.
Con un box all’interno del testo, come questo di sotto.
NdR: Eventuale titolo della nota
Questa nota è un esempio di come potremmo inserire delle note nel testo.
Con delle note “laterali” al testo, come quella evidenziata nell’immagine di sotto.
Licenza
Questa versione in HTML delle linee guida è basata sul materiale originale dell’Agenzia per l’Italia Digitale (AgID), rilasciato con licenza CC-BY 4.0.
Il materiale convertito e modificato dall’associazione onData per creare questa versione è anch’esso rilasciato sotto licenza CC-BY 4.0. Sei libero di:
- Condividere — riprodurre, distribuire, comunicare al pubblico, esporre in pubblico, rappresentare, eseguire e recitare questo materiale con qualsiasi mezzo e formato per qualsiasi fine, anche commerciale.
- Modificare — remixare, trasformare il materiale e basarti su di esso per le tue opere per qualsiasi fine, anche commerciale.
Devi riconoscere i crediti appropriati citando l’Agenzia per l’Italia Digitale (AgID) per il materiale originale e l’associazione onData per la conversione e le modifiche. Inserisci anche il link all’homepage di questo progetto:
https://ondata.github.io/linee-guida-opendata/