Docs Italia beta

Documenti pubblici, digitali.

5. Pubblicare un documento

Dopo aver scritto la documentazione in formato RST, è possibile avviare la fase di pubblicazione.

In questo capitolo vengono forniti alcuni chiarimenti sul repository di configurazione, sul repository del documento e sul backend di Docs Italia.

5.1. Repository di configurazione

Il repository di configurazione deve essere chiamato italia-conf e contenere le informazioni (metadati) relative al publisher, ai progetti e ai documenti correlati che appaiono in vari punti all’interno delle pagine su Docs Italia.

Puoi modificare i file nel repository di configurazione presente nello Starter kit come descritto qui sotto. Successivamente, dovrai caricare i file sul repository remoto creato in precedenza (vedi Come pubblicare un documento) usando una delle due procedure descritte in Appendice.

example

Repository di configurazione di prova

Lo Starter kit contiene un esempio di repository di configurazione. Consulta le istruzioni contenute nel kit per conoscere come modificare i file.

5.1.1. Contenuto del repository

Il repository di configurazione deve contenere due file principali:

  1. publisher_settings.yml, per i metadati relativi al publisher;
  2. projects_settings.yml, per i metadati relativi ai progetti.

In questi file vengono specificati, per esempio, quali progetti appartengono al publisher e quali repository del documento appartengono a un determinato progetto. In aggiunta, nel repository di configurazione possono essere inclusi i loghi del publisher o dei progetti.

Oltre ai metadati liberamente modificabili, esiste un set di tag tratti da un vocabolario controllato, condiviso fra Docs Italia e Forum Italia. Tramite questi tag (almeno 5 per ciascun publisher o progetto) si stabilisce un collegamento fra i contenuti di Docs Italia e gli argomenti nel Forum, permettendo agli utenti di trovare più rapidamente quello che cercano.

Le Tabelle 2 e 3 illustrano alcuni dei possibili metadati che è possibile specificare nei file di configurazione. Gli esempi associati mostrano come formattare i file di configurazione. Per maggiori informazioni è possibile consultare le istruzioni allegate allo Starter kit.

5.1.2. Metadati del publisher

Importante

I campi name e description sono obbligatori.

Tabella 5.1 Alcuni dei metadati associati al publisher.
Parametro Descrizione
name Il nome per esteso dell’Ente associato al publisher
description Una descrizione estesa delle funzioni e degli scopi dell’Ente
short_name Il nome abbreviato dell’Ente associato al publisher o l’acronimo (opzionale)
motto Il motto o una breve frase che contraddistingue l’Ente (opzionale)
logo L’URL del logo (può essere contenuto nel repository di configurazione) (opzionale)
website L’URL del sito dell’Ente (opzionale)
address L’indirizzo della sede dell’Ente (opzionale)
tags La lista dei tag che descrivono il publisher (opzionale)

example

File publisher_settings.yml tratto dallo Starter kit

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
publisher:
  name: Ministero della Documentazione Pubblica
  description:
    Lorem ipsum dolor sit amet, consectetur
    adipisicing elit, sed do eiusmod tempor
    incididunt ut labore et dolore magna aliqua.
    Ut enim ad minim veniam, quis nostrud
    exercitation ullamco laboris nisi ut
    aliquip ex ea commodo consequat.
    Duis aute irure dolor in reprehenderit in
    voluptate velit esse cillum dolore eu
    fugiat nulla pariatur. Excepteur sint
    occaecat cupidatat non proident, sunt in
    culpa qui officia deserunt mollit anim id
    est laborum.
  short_name: Min. Doc. Pub.
  website: https://www.ministerodocumentazione.gov.it
  tags:
    - documents
    - public
    - amazing publisher
  logo: assets/images/logo.svg

5.1.3. Metadati dei progetti

Importante

I campi name, description e documents sono obbligatori.

Tabella 5.2 Alcuni dei metadati associati a ciascun progetto.
Parametro Descrizione
name Il nome per esteso del progetto
description Una descrizione estesa delle funzioni e degli scopi del progetto
documents La lista dei documenti afferenti al progetto, identificati tramite i nomi dei loro repository
short_name Il nome abbreviato del progetto o l’acronimo (opzionale)
logo L’URL del logo (può essere contenuto nel repository di configurazione) (opzionale)
website L’URL del sito del progetto (opzionale)
start_date La data di inizio del progetto (opzionale)
end_date La data di fine del progetto (opzionale)
tags La lista dei tag che descrivono il progetto (opzionale)

example

File projects_settings.yml tratto dallo Starter kit

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
projects:
  - name: Progetto Documentato Pubblicamente
    description:
      Lorem ipsum dolor sit amet, consectetur
      adipisicing elit, sed do eiusmod tempor
      incididunt ut labore et dolore magna aliqua.
      Ut enim ad minim veniam, quis nostrud
      exercitation ullamco laboris nisi ut
      aliquip ex ea commodo consequat.
      Duis aute irure dolor in reprehenderit in
      voluptate velit esse cillum dolore eu
      fugiat nulla pariatur. Excepteur sint
      occaecat cupidatat non proident, sunt in
      culpa qui officia deserunt mollit anim id
      est laborum.
    documents:
      - project-document-doc
      - another-project-document-doc
    short_name: PDP
    website: https://progetto.ministerodocumentazione.gov.it
    tags:
      - digital
      - citizenship
      - amazing project

5.2. Repository del documento

Dopo aver inserito il repository del documento fra quelli presenti nel file projects_settings.yml, è possibile importare il documento dal backend di Docs Italia. Per una corretta compilazione, il repository del documento deve contenere come minimo alcuni file specifici.

example

Repository del documento di prova

Lo Starter kit contiene un esempio di repository del documento. Consulta le istruzioni contenute nel kit per conoscere come modificare i file.

Prima di pubblicare il documento su Docs Italia, l’utente deve:

  1. Modificare il file README.md, descrivendo il contenuto del repository;
  2. Modificare il file index.rst e inserire i file della documentazione;
  3. Modificare il file LICENSE;
  4. Modificare il file document_settings.yml.

Consulta le sezioni seguenti per maggiori informazioni su come modificare questi file.

5.2.1. Struttura del repository

Lo Starter kit suggerisce l’uso di una struttura del repository del documento di questo tipo:

example

Struttura del repository

1
2
3
4
5
6
7
+-- README.md
+-- index.rst
+-- titolo-capitolo-1.rst
+-- titolo-capitolo-2.rst
+-- LICENSE
+-- AUTHORS
+-- document_settings.yml

Il repository dovrà comprendere, come requisito minimo:

  1. Un file README.md, che serve da homepage del repository su GitHub e in cui viene descritto il contenuto del repository stesso.
  2. Un file index.rst, che corrisponderà alla pagina principale del sito della documentazione.
  3. I file titolo-capitolo-1.rst e titolo-capitolo-2.rst, come esempio di capitoli del documento.
  4. I file LICENSE e AUTHORS, che specificano la licenza d’uso associata al repository e l’attribuzione dei diritti d’autore.
  5. Un file document_settings.yml, che specifica i metadati associati al documento.

5.2.2. File README.md

Il file README.md rappresenta la prima pagina che gli utenti vedono quando accedono a un repository su GitHub. Deve fornire le informazioni sul contenuto del repository stesso e viene redatto usando la sintassi Markdown, che differisce dal formato RST discusso in precedenza. Puoi consultare l’esempio contenuto nello Starter kit.

Il file README.md comincia con un titolo con il seguente formato:

# Nome_Progetto, Nome_Documento

Il segno # indica un titolo e Nome_Documento (obbligatorio) serve a distinguere diversi documenti relativi, per esempio, ad aspetti diversi di uno stesso progetto.

All’inizio del README, indica il link alla documentazione su Docs Italia, assieme al/ai link ai testi di partenza, se presenti.

5.2.3. File index.rst

Il file index.rst corrisponde alla home page del documento e serve ad almeno tre scopi:

  1. Visualizzare il titolo del documento;
  2. Fornire un’introduzione al testo;
  3. Visualizzare un indice di tutte le pagine contenute.

Puoi trovare maggiori informazioni sulla struttura dell’indice del documento in Appendice.

5.2.4. Struttura del documento

I vari capitoli del documento sono contenuti in file separati allo stesso livello del file index.rst. Per documenti più complessi, con sezioni su più livelli, la struttura consigliata è descritta in Appendice.

5.2.5. File LICENSE e AUTHORS

Il file LICENSE specifica il tipo di licenza associata alla documentazione. Le licenze sono identificate attraverso il loro codice SPDX.

Per i documenti contenuti in Docs Italia, è obbligatorio indicare una licenza aperta. Il suggerimento è di usare una delle seguenti opzioni:

  • CC-BY-4.0 per la documentazione;
  • CC0-1.0 per le leggi, gli schemi e i documenti normativi.

Nel caso di licenza CC-BY-4.0 è obbligatorio creare un file AUTHORS che contiene l’attribuzione della proprietà dei diritti d’autore. Nel caso di licenza CC0-1.0 è possibile farlo (MAY) ma non è obbligatorio.

Per maggiori informazioni, è possibile consultare il README per le licenze del Team per la Trasformazione Digitale.

5.2.6. File document_settings.yml

Il file document_settings.yml specifica i metadati associati al documento, in modo simile a quanto fatto in precedenza per publisher e progetto. Il documento eredita i metadati relativi al publisher e al progetto da quelli presenti nei file del repository di configurazione, se presenti.

I metadati facilitano la ricerca delle informazioni da parte degli utenti. In particolare, anche per i documenti è previsto l’uso di tag tratti da un vocabolario controllato per permettere l’integrazione fra Docs Italia e il Forum (vedi anche Repository di configurazione).

La Tabella 5.3 mostra un elenco dei possibili metadati e una loro descrizione. L’esempio successivo mostra il file document_settings.yml contenuto nello Starter kit.

Importante

I campi name, description e tags sono obbligatori per la corretta compilazione del documento.

Tabella 5.3 Alcuni dei metadati associati a ciascun documento. I campi contrassegnati con l’asterisco sono obbligatori.
Parametro Descrizione
name (*) Il nome per esteso del documento
description (*) Una descrizione estesa delle funzioni e degli scopi del documento
tags (*) La lista dei tag che descrivono il documento
short_name Il nome abbreviato del documento (opzionale)
author Chi ha creato il documento, username GitHub (opzionale)
contributors Chi ha collaborato alla stesura del testo: nomi e cognomi (opzionale)
published La data in cui il documento è stato pubblicato per la prima volta (opzionale)
expiration La data in cui il documento diventa obsoleto, utilizzabile per nascondere documenti non più validi (opzionale)
id Un identificativo univoco della documentazione (opzionale)
license Il tipo di licenza associato al documento (opzionale)
origin L’URL del documento di partenza (opzionale)
software_website L’URL del software a cui la documentazione si riferisce (opzionale)
audience A chi è rivolto il documento (ad es. cittadini, comuni, software house, ecc) (opzionale)
type Il tipo di documento (ad es. linee guida, documentazione tecnica, leggi, procedure, ecc) (opzionale)

example

File document_settings.yml tratto dallo Starter kit

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
document:
  name: Titolo del documento
  description: |
    Lorem ipsum dolor sit amet, consectetur
    adipisicing elit, sed do eiusmod tempor
    incididunt ut labore et dolore magna aliqua.
    Ut enim ad minim veniam, quis nostrud
    exercitation ullamco laboris nisi ut
    aliquip ex ea commodo consequat.
    Duis aute irure dolor in reprehenderit in
    voluptate velit esse cillum dolore eu
    fugiat nulla pariatur. Excepteur sint
    occaecat cupidatat non proident, sunt in
    culpa qui officia deserunt mollit anim id
    est laborum.
  tags:
    - topic
    - related topic
    - amazing project

5.3. Funzione commenti con Forum Italia

Per attivare la funzione commenti, inserisci questo script (e gli id necessari, che ti verranno forniti dagli amministratori di Docs Italia) in ciascuna delle sezioni che vuoi rendere commentabili. I commenti saranno visibili anche su Forum Italia.

Docs Italia è completamente integrato con Forum Italia, la piattaforma di discussione sui progetti digitali della Pubblica Amministrazione.

Tramite le funzionalità di Discourse, è possibile aggiungere dei commenti ai propri documenti. Ciascun commento inserito su Docs Italia è automaticamente visibile anche su uno specifico topic in Forum Italia. Viceversa, quando vengono inseriti dei commenti nel topic sul Forum, questi sono subito visibili anche nel documento su Docs Italia.

5.3.1. Aggiungere i commenti nel documento

Al momento, è possibile aggiungere un thread di commenti per ciascuna pagina. Questo corrisponde a un singolo topic nel Forum.

Quando richiedi l’autorizzazione a pubblicare un documento su Docs Italia, gli amministratori creeranno per te una Categoria nel Forum dove verranno visualizzati i commenti al tuo documento.

Per ciascun argomento nel Forum, ti verrà assegnato un <topic-id> dagli amministratori. Per creare i commenti in una pagina, copia lo script seguente alla fine del file RST corrispondente:

.. discourse::

:topic_identifier: <topic-id>

sostituendo <topic-id> con il codice opportuno.

example

Il codice da inserire per il topic con ID 1234 è:

1
2
3
.. discourse::

:topic_identifier: 1234

Ripetendo questa procedura, è possibile collegare ciascuna pagina del documento con il corrispondente argomento sul Forum. In caso di problemi, è possibile contattare gli amministratori di Docs Italia.

5.4. Caricare i file sul repository remoto

Tutti i file necessari alla creazione del documento su Docs Italia devono essere caricati nel repository del documento remoto, in modo che Docs Italia possa aggiornare la pagina del documento, attualmente vuota. Ogni documento su Docs Italia viene aggiornato automaticamente ogni qual volta viene effettuata una modifica al repository di configurazione o del documento.

Le procedure da utilizzare per caricare i file sono descritte in Appendice.

5.5. Backend di Docs Italia

Docs Italia possiede una modalità di backend, ovvero una piattaforma accessibile dagli utenti autorizzati dove è possibile eseguire alcune attività di amministrazione avanzata (vedi Figura 5.1).

L’utente può accedere al backend di Docs Italia semplicemente con il proprio account GitHub.

Backend di Docs Italia

Fig. 5.1 Il backend di Docs Italia per gestire un documento.

Nota

Al primo accesso, l’utente deve autorizzare a sua volta la piattaforma a interagire con la propria organizzazione GitHub: tale operazione è necessaria per consentire l’aggiornamento del documento a ogni modifica del repository.

Il backend permette di modificare le impostazioni avanzate, come l’attivazione o meno di determinate versioni di un documento o l’aggiornamento manuale delle pagine. Da qui, l’utente può gestire tutti i documenti corrispondenti ai repository di una determinata organizzazione per i quali ha i permessi di scrittura.

Dal backend sarà possibile accedere ad alcuni widget relativi al publisher, ai progetti o ai documenti. Per esempio, la lista dei progetti, la lista dei documenti e l’indice di un documento.

5.5.1. Anteprima del documento

Docs Italia prevede la possibilità di creare un’anteprima dei documenti privata, non raggiungibile tramite i collegamenti all’interno della piattaforma, in modo da poterla controllare prima di renderla pubblica.

I documenti privati sono raggiungibili dal publisher cliccando sul pulsante Mostra Documenti nel backend della piattaforma. Tali documenti possono essere resi pubblici in un secondo tempo tramite un’apposita impostazione nel backend di Docs Italia.

La Figura 5.2 mostra com’è possibile impostare un documento privato su Docs Italia.

Documenti privati

Fig. 5.2 Il backend di Docs Italia permette di impostare documenti privati.

5.5.2. Documenti in lingue multiple

Docs Italia permetterà di gestire i documenti e le loro traduzioni. L’utente potrà leggere il documento in un’altra lingua in qualsiasi pagina si trovi, semplicemente selezionando il pulsante corrispondente. Questa funzionalità verrà presto aggiunta alla piattaforma.