Questo repository contiene il testo delle Linee guida di design per i servizi digitali della PA in formato reStructredText.
Le linee guida per il design dei servizi digitali della Pubblica Amministrazione sono uno strumento di lavoro per la Pubblica Amministrazione e servono ad orientare la progettazione di ambienti digitali fornendo indicazioni relative al service design, alla user research, al content design e alla user interface. Per discutere sul design dei servizi pubblici è disponibile il nostro forum. Per collaborare alle linee guida è possibile usare gli strumenti descritti di seguito.
Le linee guida sono un documento pubblico, e chiunque può partecipare al processo di revisione e aggiornamento attraverso gli strumenti messi a disposizione attraverso GitHub, in particolare le issues (per le discussioni) e le pull request (per le proposte di modifica).
I contenuti delle linee guida sono scritti in file .rst e possono essere aggiornati via GitHub. Qui è disponibile una guida alla sintassi RST.
Altre risorse per l'editing in formato .rst sono:
Le linee guida di design seguono le roadmap di evoluzione pubblicate in ciascuna delle sezioni di Designers Italia
Le linee guida beneficiano del version control system di GitHub, per cui esiste una traccia pubblica di tutte le modifiche effettuate e dei relativi autori.
Le linee guida di design adottano un sistema di release basato sui tag di GitHub. Ogni release è etichettata secondo un sistema basato su anno e versione. Le versioni sono espresse attraverso un numero progressivo. Il sistema delle release è in vigore dal 2017, quindi la prima release delle linee guida è 2017.1 (prima release del 2017).
I nuovi contenuti e le modifiche a contenuti esistenti dopo essere approvati vengono pubblicati nella versione latest delle linee guida, disponibile per una discussione pubblica e revisione da parte della community ma priva di valore ufficiale.
Solo successivamente, in occasione di una nuova release delle linee guida, il team di Designers Italia decide di consolidarle e farle confluire, dopo eventuali modifiche, nella versione ufficiale stable delle linee guida.
Le linee guida sono scritte seguendo la style guide di redazione dei testi pubblici. In particolare:
- linguaggio semplice e comprensibile ad un pubblico ampio
- brevità e uso di elenchi
- ricorso ad esempi, meglio se supportati da immagini e link
Nella guida usiamo delle etichette per evidenziare alcuni passaggi, specificando se l'applicazione della indicazione è obbligatoria o facoltativa, come segue
- si deve (devi)
- si può (puoi)
- si dovrebbe (dovresti)
- best practice
La documentazione è disponibile su Docs Italia, la piattaforma di gestione della documentazione pubblica creata da Team per la Trasformazione Digitale.
Le funzioni di hosting e di ricerca sono basate su ReadTheDocs e la documentazione viene pubblicata attraverso il tool Sphinx e il linguaggio RST.
Tutti i documenti di Docs Italia possono essere fruiti anche in formato .epub e .pdf
I file contenuti in questo repository possono essere modificati sul proprio computer ed essere convertiti in formato HTML per validarne i cambiamenti. È necessario innanzitutto installare il tema di Docs Italia attraverso il seguente comando:
pip install -r requirements.txt
Quindi lanciare il comando Sphinx per validare e generare la documentazione, che sarà consultabile all'indirizzo ./html/index.html:
sphinx-build -n -W -T -b html . html