styleguide e workflow documentazione

[sbronzolo]

Proposta per testo testo introduttivo alle linee guida (e anche per aggiornamento readme del repo
https://github.com/italia/design-doc/blob/master/README.md
comprensivo di styleguide e workflow pubblicazione documentazione, dopo introduzione versionamento

Le linee guida di design
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.

Sviluppo collaborativo
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
Editor per il testo
Editor per le tabelle
Estensione Chrome per Google spreadheet
Altro

Version control e release della documentazione
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.

Stile della documentazione
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

Consultazione della documentazione
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 Readhtedocs 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

Kit di sviluppo e di design
Il progetto di design dei servizi pubblici digitali prevede che oltre al rilascio di linee guida ci sia il rilascio di kit di sviluppo e di design per i siti pubblici (ad es. icon kit, kit di sviluppo, ecc.). I kit - e la documentazione dei kit - possono essere citati all'interno delle linee guida, ma non sono contenuti all'interno di questo repo. I kit sono espressione delle linee guida, ma il versionamento delle linee guida e quello dei kit sono processi indipendenti.

[matteodesanti]

Grazie @sbronzolo !
Aggiungo di seguito qualche commento.

1.
Modificherei il titolo del documento da

Linee guida di design per i servizi web della PA

a

Linee guida di design per i servizi digitali della PA

Allo stesso modo modificherei il titolo in questa intro.

2.
Propongo di sostituire

meglio se supportati da foto e link

con

meglio se supportati da immagini e link

3.
Aggiungerei infine un paragrafo che faccia riferimento al forum come strumento principale per discutere in maniera aperta di dubbi, proposte o integrazioni che non sono ancora sufficientemente strutturate per diventare una issue in questo repo.

Per il resto è perfetto.

[pdavide]

• Includerei parte di quanto proposto per il file README anche in un file CONTRIBUTING.
• Inserirei i riferimenti alle pagine help di GitHub a proposito di issues e pull request.
• Inserirei link alla versione latest e alla versione stable delle linee guida.
• Inserirei il link ad un file (visualizzato in raw) del repo per mostrare l'utilizzo della direttiva rst ".. adminition" per le etichette SI DEVE, SI DOVREBBE, etc. Me lo linki per favore @pdavide

inoltre @pdavide vogliamo dettagliare il metodo di tagging delle release? Posso lincare questo https://help.github.com/articles/about-releases/
o è meglio essere più precisi?

[roby986]

Segnalo giusto due cose:

• modificherei il titolo di

Sviluppo collaborativo e version control

visto che nel paragrafo si spiega solo la parte di scrittura collaborativa e che al versioning è dedicato il paragrafo seguente.

• c'è un piccolo errore di formattazione in "Kit di sviluppo e di design": la parentesi alla fine della prima frase non viene chiusa:

(ad es. icon kit, kit di sviluppo, ecc.)

[pdavide]

Issue resolved in #46 and #37