Linee guida documentazione

Linee guida documentazione

Introduzione

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.

Regole generali

1. Scrivere in italiano
   Usare le regole della lingua italiana ed evitare, quando possibile, i termini inglesi.

2. Scrivere in modo impersonale
   Evitare espressioni come "installa l'applicazione", "copiate il codice"; utilizzare invece espressioni come "installare l'applicazione", "copiare il codice".

3. Less is more
   Evitare periodi eccessivamente lunghi, è consigliato invece l'uso di elenchi puntati o numerati quando possibile. Questo permette di rendere chiari i passaggi da eseguire. Limitare inoltre al minimo indispensabile l'uso di immagini, col tempo dovranno essere aggiornate.

4. Sfruttare le guide esistenti
   Se nella propria guida deve essere inserita una procedura presente in un'altra pagina, evitare di duplicarla. Inserire invece un link alla guida esistente.

5. Evitare il superfluo
   La documentazione serve per spiegare aspetti più o meno complessi legati ad Odoo. Sono guide che permettono di eseguire procedure spesso complicate, o di aiutare gli utenti alla risoluzione dei problemi. Non è necessario creare documenti per applicazioni già documentate o per procedure banali per le quali non servono spiegazioni.

Metodo dettagliato

Controllare il forum/lista

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

Segnalare l'interesse alla 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.

Segnalare la presa in carico

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.

Verificare la comprensibilità del readme

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.

Usare il modulo provandone le varie funzionalità

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.

Redarre il documento

Utilizzando le linee guida, realizzare il documento con uno dei due strumenti previsti:

• LibreOffice Write

• RST

Mettere a disposizione il documento

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.

Segnalare che il documento è pronto per la revisione

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.

Revisione

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.

Pubblicazione

Il documento definitivo viene pubblicato dal revisore in YYYYY

Suggerimenti

Formati

• 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

Ruoli

Coordinatori

Coordinano l'attività del gruppo supervisionando la qualità e la coerenza della documentazione aggiornandone gli standard

Revisori

Effettuano la verifica dei documenti in versione finale e li pubblicano.

Editori

Realizzano i documenti interfacciandosi con gli sviluppatori e considerando le osservazioni degli altri editori, partecipano alla revisione dei documenti in sviluppo degli altri editori.