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¶

 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¶

 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.1. Struttura del repository¶

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

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.

 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.1. Aggiungere i commenti nel documento¶

Al momento, è possibile aggiungere uno o più thread di commenti per ciascuna pagina. Ogni thread corrisponde a uno specifico 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 abilitare i commenti, copia lo script seguente nel punto in cui vuoi visualizzarli:

.. forum_italia::
   :topic_id: <topic-id>

sostituendo <topic-id> con il codice opportuno.

1
2

.. forum_italia::
   :topic_id: 1234

Ripetendo questa procedura, è possibile collegare sezioni specifiche del documento con il corrispondente argomento sul Forum.

Se vuoi attivare le funzionalità di commento per l’intera pagina, dovrai aggiungere l’opzione :scope: document e inserire il codice seguente alla fine della pagina.

.. forum_italia::
   :topic_id: <topic-id>
   :scope: document

In caso di problemi, è possibile contattare gli amministratori di Docs Italia.

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.

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.