-
-
Notifications
You must be signed in to change notification settings - Fork 307
Linee guida documentazione
In questo documento vengono illustrate le regole generali, il metodo di lavoro dettagliato e alcuni suggerimenti per realizzare una valida documentazione.
-
Scrivere in italiano
Usare le regole della lingua italiana ed evitare, quando possibile, i termini inglesi. -
Scrivere in modo impersonale
Evitare espressioni come "installa l'applicazione", "copiate il codice"; utilizzare invece espressioni come "installare l'applicazione", "copiare il codice". -
Less is more
Evitare periodi eccessivamente lunghi, è invece consigliato 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. -
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. -
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 legate a moduli specifici, o 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.
Se si vuole proporre una nuova guida o richiedere nuovi documenti, inviare un messaggio con la seguente struttura:
-
titolo: CFD-nome_modulo
Se invece di un modulo si tratta di una funzionalità, identificare un nome da utilizzare che sia il più possibile sintetico -
contenuto: breve descrizione del modulo o della funzionalità
Descrizione utile a identificare i punti chiave necessari per la documentazione
Richiedere l'assegnazione, proponendosi come editore, rispondendo in lista al messaggio originale.
Se per uno stesso documento si propongono più persone al ruolo di editore, è opportuno accordarsi per definire come organizzare il lavoro di gruppo definendo anche un referente. Se si tratta di un gruppo di lavoro è opportuno che i messaggi siano inviati dal referente, che deve indicare anche il gruppo di lavoro.
Nel caso di moduli, il primo controllo da effettuare è che il file README.md sia comprensibile e fornisca le prime indicazioni di utilizzo del modulo. In caso contrario contattare lo sviluppatore del modulo chiedendo le opportune modifiche.
Utilizzando lo strumento runbot (o 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 scegliendo uno dei due strumenti previsti:
- Editor di testo RST online o installato in locale
- LibreOffice Write
Quando il documento raggiunge un avanzamento tale da poter essere visionato (anche se non completo), va reso visibile per consentire ad altri editori di dare una mano effettuando 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 in ML proseguendo la discussione nell'apposito thread.
Quando il documento è stato completato, inviare un messaggio in ML sempre in risposta alla richiesta originale di documentazione, indicando dove si trova il documento.
Un revisore prenderà quindi in carico il documento inviando un messaggio di risposta in ML, restando sempre nel thread originale. Attraverso messaggi in lista, revisioni su GitHub o discussioni nel canale Telegram (per cose più semplici), il revisore interagisce con gli editori e/o con gli sviluppatori per arrivare al documento definitivo.
Il documento definitivo viene pubblicato dal revisore in YYYYY
Coordinano l'attività del gruppo supervisionando i lavori e gestendo eventuali controversie e criticità
Effettuano il controllo dei documenti verificandone la qualità e la coerenza in rapporto agli standard delle linee guida. Quando la documentazione è pronta si occupano della pubblicazione.
Realizzano i documenti interfacciandosi con gli sviluppatori e applicano le osservazioni dei revisori.
Dopo un periodo di prova necessario a recepire e assimilare le linee guida, possono essere proposti a ruolo di revisore con votazione in ML da parte degli altri revisori.