Skip to content

Linee guida documentazione

Sergio Zanchetta edited this page Mar 31, 2019 · 5 revisions

Linee guida documentazione

Introduzione

In questo documento vengono illustrate le regole generali, il metodo di lavoro dettagliato e alcuni suggerimenti per realizzare una valida documentazione.

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, è 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.

  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 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.

Metodo di lavoro dettagliato

Segnalare nuove proposte o richieste in mailing list

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

Segnalare l'interesse e la presa in carico del documento

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.

Verificare la comprensibilità del readme

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.

Usare il modulo provandone le varie funzionalità

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.

Redarre il documento

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

  • Editor di testo RST online o installato in locale
  • LibreOffice Write

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 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.

Segnalare che il documento è completo e pronto per la revisione

Quando il documento è stato completato, inviare un messaggio in ML sempre in risposta alla richiesta originale di documentazione, indicando dove si trova il documento.

Revisione

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.

Pubblicazione

Il documento definitivo viene pubblicato dal revisore in YYYYY

Ruoli

Coordinatori

Coordinano l'attività del gruppo supervisionando i lavori e gestendo eventuali controversie e criticità

Revisori

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.

Editori

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.

You can’t perform that action at this time.