Misc minor improvements (#43)

alranel · libremente · commit 7da272bd7df2 · 2019-03-04T17:26:39.000+01:00
* Update Docs Italia title and description
* Move intro to the index file
diff --git a/docs/en/country.rst b/docs/en/country.rst
@@ -1,7 +1,7 @@
 .. _`country-extension`:
 
-Country-Specific Sections
-=========================
+Country-Specific Extensions
+===========================
 
 While the standard is structured to be meaningful on an international
 level, there are additional information that can be added that makes
diff --git a/docs/en/index.rst b/docs/en/index.rst
@@ -1,5 +1,33 @@
-The ``publiccode.yml`` Standard
-===============================
+``publiccode.yml``
+==================
+
+``publiccode.yml`` is a metadata standard for repositories containing software developed or acquired by the Public Administration, aimed at making them easily discoverabile and thus reusable by other entities.
+
+By including a ``publiccode.yml`` file in the root of a repository, and populating it with information about the software, technicians and civil servants can evaluate it. Automatic indexing tools can also be built, since the format is easily readable by both humans and machines.
+
+``publiccode.yml`` is mandatory for all public software developed in Italy, according to the national [guidelines](https://docs.italia.it/AgID/linee-guida-riuso-software/lg-acquisizione-e-riuso-software-per-pa-docs/): this enables the Developers Italia crawler to build the national [software catalog](https://developers.italia.it/). The standard is designed to be interoperable internationally, thus the country-specific keys are separated by the core part and are defined in specific sections that each government can rule.
+
+Details carried by a ``publiccode.yml`` file include: 
+
+-  title and description of the project or product (in one or more languages); 
+-  development state (e.g., ``concept``, ``development``, ``beta``,
+  ``stable``, ``obsolete``; 
+-  contacts of the entity who published the codebase; 
+-  contacts of the maintainer, if any, including the expire date of the maintainance contract; 
+-  information about the legal context for which the project or product was designed; 
+-  dependencies.
+  
+and much more.
+
+See also
+----------
+
+- [More information about software reuse](https://developers.italia.it/en/reuse)
+- [publiccode.yml web editor](https://publiccode-editor.developers.italia.it/)
+
+Table of contents
+-----------------
+
 .. toctree:: 
    :maxdepth: 2
    :numbered:
diff --git a/docs/en/schema.rst b/docs/en/schema.rst
@@ -1,5 +1,5 @@
-The Standard
-============
+The Standard (core)
+===================
 
 This document represents the description of the ``publiccode.yml``
 schema.
diff --git a/docs/it/country.rst b/docs/it/country.rst
@@ -1,9 +1,9 @@
 .. _`estensioni-paese`:
 
-Chiavi e Sezioni Specifiche per Paese
-=====================================
+Estensioni nazionali
+====================
 
-Mentre lo standard è strutturato per essere significativo a livello
+Mentre il core è strutturato per essere significativo a livello
 internazionale, vi sono informazioni addizionali che possono essere
 aggiunte a livello nazionale, come ad esempio una dichiarazione di
 compatibilità con una legge locale. Il meccanismo di estensione fornito
@@ -26,9 +26,6 @@ Dunque, se un software è compatibile, troveremo:
 
 Nota bene che le chiavi *country-specific* **non** sono valide
 all’interno delle sezioni internazionali. I Paesi che vogliano estendere
-il formato dovrebbero aggiungere una sezione dedicata.
-
-La documentazione per queste estensioni *country-specific* è mantenuta
-in file separati.
+il formato devono aggiungere una sezione dedicata.
 
 .. include:: schema.it.rst
diff --git a/docs/it/index.rst b/docs/it/index.rst
@@ -1,10 +1,38 @@
 Lo Standard ``publiccode.yml``
 ==============================
+
+``publiccode.yml`` è uno standard di metadati ideato per essere inserito in repository contenenti software della Pubblica Amministrazione con lo scopo di renderli facilmente individuabili e, di
+conseguenza, riutilizzabili da altri enti.
+
+Inserendo nella root di un repository un file chiamato ``publiccode.yml`` che descrive le caratteristiche del software se ne agevola la comprensione ai tecnici e ai decisori pubblici interessati a valutarlo; al tempo stesso si permette di costruire strumenti automatici di indicizzazione, poiché il formato è facilmente leggibile sia da esseri umani sia da macchine.
+
+``publiccode.yml`` è obbligatorio per tutto il software pubblico sviluppato in Italia, come da [linee guida](https://docs.italia.it/AgID/linee-guida-riuso-software/lg-acquisizione-e-riuso-software-per-pa-docs/): questo consente al crawler automatico di Developers Italia di costituire il [catalogo del software a riuso](https://developers.italia.it/). Lo standard è tuttavia pensato in ottica internazionale, per cui tutte le specificità nazionali sono separate dal core e definite in apposite sezioni estensibili autonomamente dai governi nazionali.
+
+Tra le informazioni contenute in un ``publiccode.yml`` vi sono: 
+
+- il titolo e la descrizione del progetto o prodotto (in una o più lingue); 
+-  lo stato dello sviluppo ad es., ``concept``, ``development``, ``beta``,
+  ``stable``, ``obsolete``; 
+-  i riferimenti dell’organizzazione che ha sviluppato il progetto; 
+-  chi si sta occupando della sua manutenzione e quando il rapporto finirà; 
+-  per quale quadro giuridico è stato pensato questo progetto o prodotto; 
+-  quali dipendenze software esistono.
+  
+e molte altre informazioni rilevanti.
+
+Link utili
+----------
+
+- [Maggiori informazioni sul riuso del software](https://developers.italia.it/it/riuso)
+- [Editor web per publiccode.yml](https://publiccode-editor.developers.italia.it/)
+
+Indice dei contenuti
+--------------------
+
 .. toctree:: 
    :maxdepth: 2
    :numbered:
 
-   intro.rst
    schema.rst
    country.rst 
    forks.rst
diff --git a/docs/it/intro.rst b/docs/it/intro.rst
diff --git a/docs/it/schema.it.rst b/docs/it/schema.it.rst
@@ -1,7 +1,7 @@
 .. _estensioni-italiane:
 
-Chiavi e Sezioni italiane
--------------------------
+Italia
+------
 
 Tutte le estensioni elencate qui di seguito sono specifiche per l'Italia e, di
 conseguenza, devono essere inserite in una sezione denominata con 
diff --git a/docs/it/schema.rst b/docs/it/schema.rst
@@ -1,5 +1,5 @@
-Lo standard
-===========
+Lo standard (core)
+==================
 
 La struttura di un file ``publiccode.yml`` prevede l'esistenza di chiavi
 top-level e sezioni che possono contenere al proprio interno altre chiavi. 
diff --git a/document_settings.yml b/document_settings.yml
@@ -1,9 +1,11 @@
 document:
-  name: Standard publiccode.yml
+  name: publiccode.yml
   description: |
-    Questo documento contiene la documentazione relativa allo standard publiccode.yml.
+    publiccode.yml è lo standard di metadatazione del software pubblico, richiesto dalle Linee Guida per l'Acquisizione e il Riuso del Software per la Pubblica Amministrazione.
   tags:
     - publiccode.yml 
     - standard 
     - interoperabilità
     - riuso
+    - software
+  
