Docs Italia beta

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

Che cosa è questo tutorial

_images/docs-.png

Fig. 1 immagine rilasciata con licenza CC0

Questo tutorial ha l’obiettivo di spiegare due modalità per la creazione di un Documento da visualizzare tramite la piattaforma Read the Docs, secondo le specifiche della Guida «Docs Italia» del Team Trasformazione Digitale dell’AgID (Agenzia per l’Italia Digitale).

Read The Docs è un servizio online gratuito che semplifica la gestione della documentazione relativa ad una pubblicazione, e consente di automatizzare:

  • la creazione dei documenti,
  • il controllo delle versioni della pubblicazione che possono essere aggiornate nel tempo,
  • l’hosting dei singoli documenti pubblicati.

A chi si rivolge il tutorial

Il tutorial si rivolge principalmente ai dipendenti e dirigenti di ogni tipologia di Pubblica Amministrazione in Italia, soprattutto a chi è responsabile della pubblicazione di documenti pubblici online, regolamenti, manuali e a chi si occupa di comunicazione istituzionale.

Non è necessario essere sviluppatori per usare le procedure che spieghiamo in questo tutorial e infatti abbiamo strutturato questo documento in più parti:

Importante

  • una destinata a chi non è molto addentro ai linguaggi di programmazione e ai sistemi di versionamento (curata da Ciro Spataro) = il capitolo 1;
  • un’altra per chi ha maggiori competenze digitali (a cura di Pablo Persico) = il capitolo 3;
  • infine una in comune alle precedenti, abbastanza semplice, che consiste nella creazione del nome del progetto da pubblicare sulla piattaforma di Read the Docs, che si svolge solo dopo aver terminato la compilazione del progetto su Github = il capitolo 2.

Ciro Spataro e Pablo Persico hanno seguito due strade diverse (capitolo 1 e capitolo 3) per raggiungere lo stesso obiettivo di pubblicazione di documenti su Read the Docs. In tal manera verrà coperta un’ampia rappresentanza (in fatto di competenze digitali) dei dipendenti e dirigenti pubblici.


Un tutorial a cura di

_images/ods-small.png

Perché questo tutorial

Il Team Trasformazione Digitale dell’AGID ha creato «Guida a Docs Italia» per consentire e agevolare le pubbliche amministrazioni ad usare il format di «Read The Docs» al fine di pubblicare atti, documenti del tipo: Decreti, Norme, Regolamenti, Linee Guida, Piani, Deliberazioni, Determinazioni, ecc.

Dopo questo lavoro del Team Trasformazione Digitale, siamo partiti in 3 Pubbliche Amministrazioni a creare documenti su Read the Docs e siamo sicuri che questo formato sarà adottato da tanti altri soggetti che lavorano in altre PA. Vogliamo fare da apripista, stimolo e anche supporto. Siamo a disposizione per aiutarvi, con piacere, partendo proprio da questo tutorial.

Questo tutorial è un lavoro integrativo a quello svolto dal Team con la Guida «Docs Italia». Un esperimento svolto per attuare i contenuti della Guida e verificare, passo passo, la comprensione delle procedure indicate.

OBIETTIVO

L’obiettivo prioritario è far in modo da diminuire le pubblicazioni online in formato PDF, che oggi rappresenta il formato più usato nei siti web della PA, ma che non consente una leggibilità nei dispositivi mobili (viene molto difficile e non è affatto pratico) e che non permette un’agevole ricerca di parole nel testo. Il formato Read the Docs, invece, soddisfa i suddetti requisiti.

DAL READ THE DOCS ALTRI FORMATI

Dal formato Read the Docs è possibile convertire, in maniera instantanea, il documento nei formati PDF, HTML ed EPUB (che è uno standard aperto specifico per la pubblicazione di libri digitali -eBook- basato su XML).

Inoltre usare «Read the Docs» consente un facile riuso dei contenuti da parte della società e di quelle pubbliche amministrazioni che manifestano interesse a questo formato di pubblicazione.


Un tutorial di sperimentazione

Questo lavoro vuole essere soprattutto sperimentazione sulle modalità con le quali si fanno cose negli uffici pubblici, pensando a migliorare la fruizione dei documenti online.

Un punto di partenza aperto a contributi esterni, un documento che possa svilupparsi anche grazie alle esperienze di soggetti di altre PA che vorranno adottare Read The Docs come strumento per diffondere cultura della documentazione della PA anche con finalità di riutilizzo e condivisione. Per questo motivo ad ogni pagina del tutorial abbiamo pensato di inserire una sezione per riveceve i commenti, grazie all’uso del servizio fornito da Disqus.


Attività propedeutica alla pubblicazione su Read the Docs

La Guida di Docs italia consiglia la creazione di una organizzazione su GitHub.


Licenza

_images/ccbysa.png

Quest’opera è distribuita con Licenza CC BY SA 4.0 - Creative Commons, Attribuzione, Condividi allo stesso modo, Versione 4.0 Internazionale.



Contenuti del Tutorial

torna all'inizio dei contenuti