-
-
Notifications
You must be signed in to change notification settings - Fork 320
Linee guida documentazione
In questo documento viene illustrato in modo dettagliato il metodo, i passi ed alcuni suggerimenti per realizzare una valida documentazione. Vengono inoltre mostrati i formati usati per realizzare i documenti.
Quando nasce l'esigenza di realizzare un documento viene inviato un messaggio in lista con la seguente struttura:
-
titolo: CFD-nome_modulo. Se si tratta di una funzionalità anziche di un modulo identificare un nome sintetico da utilizzare
-
contenuto: breve descrizione del modulo utile ad identificare le conoscenze necessare per la documentazione
Rispondere in lista al messaggio di chiesta di documentazione proponendosi come editore. Dopo aver verificato che non esista, creare una discussione sul forum con il titolo così formato: DOC_nome_modulo. Se dopo un paio di giorni si è gli unici ad essersi proposti si può prendere in carico l'attività. Se c'è più di un editore è opportuno dialogare sulla discussione DOC_nome_modulo per definire come organizzare il lavoro di gruppo definendo anche un referente.
Chi prende in carico la documentazione risponde in lista al messaggio originale, se si tratta di un gruppo è bene che sia il referente indicando anche il gruppo di lavoro.
Nel caso di moduli, il primo controllo da fare è che il file README.md sia comprensibile e fornisca le prime indicazioni di utilizzo del modulo.
Utilizzando lo strumento runbot o installando in locale, approfondire il funzionamento del modulo. Nel caso di funzionalità non legate a moduli seguire le indicazioni di chi ha fatto la richiesta.
Utilizzando le linee guida, realizzare il documento con uno dei due strumenti previsti:
-
LibreOffice Write
-
RST
Quando il documento raggiunge un avanzamento tale da poter essere visionato (anche se non completo) va reso visibile per consentire ad altri editori di aiutare facendo un primo controllo:
-
se il documento è redatto con LibreOffice Write, va posizionato in XXXXX
-
se il dodumento è redatto con RST, va posizionato in GitHub Odoo-Italia/documentazione/guide nella cartella del modulo (se non esiste va creata)
Eventuali discussioni rilevanti nello sviluppo della documentazione vanno gestite nel forum seguendo la discussione DOC_nome_modulo.
Quando ritenete completo il documento, va inviato un messaggio in lista di risposta alla richiesta originale di documentazione CFD-nome_modulo indicando che la documentazione è completa e dove si trova.
Un revisore prende in carico il documento inviando un messaggio in lista in risposta all'originale CFD-nome_modulo. Attraverso messaggi in lista o nel forum in caso di osservazioni rilevanti, tramite le revisioni su GitHub o canale Telegram per le più semplici, il revisore interagisce con gli editori (ed eventualmente gli sviluppatori) per arrivare ad avere il documento definitivo.
Il documento definitivo viene pubblicato dal revisore in YYYYY
-
usare l'impersonale
-
evidenziare i «Tasti»
-
evidenziare i valori, le [opzioni1 | opzioni2]
-
formato del testo: font, dimensioni titoli-capoversi-testi, elenchi puntati/numerati (elenchi, sequenze)
-
immagini: formati jpg | png, dimensioni, bordo, aree evidenziate, dati contenuti (privacy), nome cartella immagini RST
-
sezioni predefinite (note, avvertimenti, suggerimenti)
-
coerenza
-
organizzata
-
concisa
-
comprensibile
-
esempio culinario di documentazione
Coordinano l'attività del gruppo supervisionando la qualità e la coerenza della documentazione aggiornandone gli standard
Effettuano la verifica dei documenti in versione finale e li pubblicano.
Realizzano i documenti interfacciandosi con gli sviluppatori e considerando le osservazioni degli altri editori, partecipano alla revisione dei documenti in sviluppo degli altri editori.