Docs Italia beta

Documenti pubblici, digitali.

Guida a Docs Italia
Progetto: Docs Italia
Amministrazione: italia
Informazioni
Sorgente
Azioni

1. Che cos’è Docs Italia

1.1. Che cos’è

Docs Italia è un servizio ideato dal Team per la trasformazione digitale della Pubblica Amministrazione in collaborazione con AgID ed è gestito da un team interdisciplinare di sviluppatori, designer e tech writer esperti nel documentare un progetto attraverso guide, linee guida, FAQ e documentazione tecnica e amministrativa. Insieme a Forum Italia e GitHub Italia, è uno degli strumenti operativi per la trasformazione digitale dei servizi pubblici.

Al momento, Docs Italia contiene alcuni dei più importanti progetti pubblici del Paese, come ANPR (anagrafe nazionale), SPID (identità pubblica), pagoPA (sistemi di pagamento) e molti altri, visibili nella home page del sito. Altri si aggiungeranno progressivamente, sulla base delle richieste delle Pubbliche Amministrazioni che possono richiedere di utilizzare il servizio tramite Slack di Developers Italia usando il canale #docs-italia.

1.2. Obiettivi

Docs Italia nasce con l’obiettivo di cambiare il linguaggio con cui si comunicano e si gestiscono i progetti pubblici in Italia, creando strumenti di lavoro comuni a diverse culture professionali e in cui gli aspetti normativi e tecnici possano coesistere. In questo modo, si semplifica la vita di chi lavora ai progetti (in particolare i funzionari, i tecnici e i fornitori della Pubblica Amministrazione), aumentando l’efficacia dei progetti pubblici e perseguendo una impostazione di open government che favorisca l’apertura, lo scambio di idee e la collaborazione.

Docs Italia permette di gestire la documentazione tecnica di un progetto (ad es. la documentazione di pagoPA), ma anche documenti amministrativi come il Piano Triennale per l’informatica nella Pubblica Amministrazione e le linee guida (come le Linee guida di design per i servizi web della PA).

La Figura 1.1 mostra l’attuale home page di Docs Italia.

Home page di Docs Italia

Fig. 1.1 L’attuale home page di Docs Italia.

1.3. Caratteristiche

Docs Italia si ispira a cinque principi, funzionali a costruire un linguaggio comune di gestione dei progetti pubblici:

  1. il primo è che oggi, in tutto il mondo, i documenti non sono più il prodotto di un individuo e di un ufficio, ma sono sempre di più il frutto di una collaborazione che prevede il contributo di diverse persone e diversi profili professionali, tecnici, economici e amministrativi;
  2. il secondo è che la Pubblica Amministrazione, seguendo una filosofia di open government, tende a incoraggiare il contributo della comunità e di punti di vista esterni;
  3. il terzo è che la Pubblica Amministrazione ha bisogno di modalità comuni per gestire le informazioni relative a un progetto, dalle linee guida di indirizzo alla documentazione tecnica;
  4. il quarto è che i documenti non sono un oggetto statico, scolpito nella pietra o stampato nella carta, ma evolvono nel tempo: poter tenere traccia di questa evoluzione offre diversi vantaggi;
  5. il quinto è che i documenti vengono fruiti sempre più spesso su Internet, e in particolare su smartphone: la semplicità di lettura fa la differenza.

1.3.1. Nuove funzionalità

  • Docs Italia è organizzato per publisher (l’ente o il Ministero che pubblica i documenti) e per progetti (ciascun progetto può avere diversi documenti).
  • Docs Italia ha un motore di ricerca che permette di navigare tra i documenti. La funzione di ricerca diventa sempre più importante mano a mano che cresce la mole di testi pubblicati sulla piattaforma.
  • Un widget consentirà di pubblicare sul proprio sito web l’elenco dei documenti appartenenti a uno specifico publisher (ad es. Ministero delle Finanze, MIUR) e a uno specifico progetto (ad es. ANPR). Sarà inoltre possibile pubblicare l’indice del documento.
  • Attualmente è in corso di analisi lo sviluppo di una componente per LibreOffice che permetta l’esportazione e l’importazione di documenti in formato RST.
  • Ogni documento su Docs Italia è associato a un URL predittivo del tipo: docs.italia.it/<publisher>/<progetto>/<nome-documento>.

La roadmap dello sviluppo di Docs Italia è disponibile online, espressa attraverso una board di Trello.

1.4. Architettura dell’informazione

1.4.1. Publisher

Ogni documento su Docs Italia è associato a un publisher. Si tratta dell’amministrazione che pubblica il documento e che ne è la responsabile.

Ogni publisher (ad esempio un comune o un ministero) è collegato a un’organizzazione su GitHub, che a sua volta ospita tutti i repository dei documenti di quella Pubblica Amministrazione.

1.4.2. Progetto

Ogni documento su Docs Italia appartiene a un progetto, ovvero una specifica linea di lavoro o di interesse per la Pubblica Amministrazione. I documenti all’interno di uno stesso progetto hanno un tema comune, spesso relativo a una piattaforma, a una legge o a un servizio. Alcuni progetti attualmente presenti su Docs Italia sono:

  • Anpr (Anagrafe nazionale della popolazione residente);
  • SPID (Sistema di identità digitale);
  • Piano triennale per l’informatica nella Pubblica Amministrazione.

Ogni progetto è a sua volta associato a un unico publisher.

1.4.3. Pagina documento

Ciascun documento ha le seguenti caratteristiche (vedi Figura 1.2):

  1. L’utente può effettuare una ricerca specifica all’interno del documento;
  2. È sempre possibile scegliere la versione del documento tramite un apposito pulsante;
  3. È possibile consultare i metadati principali del documento, inclusi i tag;
  4. È sempre possibile scaricare il documento in formato .epub e in formato .pdf;
  5. Il pulsante “modifica su GitHub” permette di accedere al repository su GitHub dove è ospitato il documento e consente a chiunque di proporre delle modifiche al contenuto;
  6. L’indice nella barra laterale consente di passare rapidamente da una sezione all’altra.
Pagina documento

Fig. 1.2 Una pagina documento su Docs Italia.

Oltre a queste caratteristiche,

  • L’ambiente di Docs Italia è responsive, ovvero consente una perfetta fruizione dei documenti su tutti i dispositivi, compreso lo smartphone;
  • Le ancore in corrispondenza dei capitoli consentono di ottenere facilmente il link di un paragrafo. Per fare apparire l’ancora basta spostare il puntatore del mouse sopra al titolo corrispondente;
  • Alcune funzionalità di paratesto specifiche permettono di segnalare informazioni importanti, esempi, procedure e documenti in consultazione (vedi l’Appendice 2).

1.4.4. La piattaforma

  • La piattaforma di Docs Italia è basata sui progetti open source Sphinx e Read the Docs. I documenti pubblicati sono redatti in formato reStructuredText.
  • Docs Italia si presta a una ottimizzazione SEO, facilitando la ricerca dei documenti pubblici anche attraverso i motori di ricerca.
  • Docs Italia è integrato con Forum Italia (a sua volta basato sul progetto open source Discourse) per consentire di commentare i documenti.