Scrittura della documentazione di GnuCash

Se si intende migliorare la documentazione di GnuCash, questo è il posto giusto. In questa pagina verranno fornite le informazioni necessarie per iniziare.

Proprio come GnuCash è stato sviluppato nel tempo grazie all'apporto di volontari, anche la documentazione è stata preparata da sviluppatori volontari e dagli utenti con lo scopo di insegnare agli altri come utilizzare GnuCash. Questo sforzo collaborativo, ha portato alla creazione di due documenti, il manuale di aiuto e la guida ai concetti.

La comunità di GnuCash accetta qualsiasi aiuto per il miglioramento sia del programma che della documentazione. Se si intende contribuire scrivendo, modificando o traducendo la documentazione di GnuCash, questa pagina fornisce le indicazioni necessarie per poter iniziare a contribuire.

La documentazione di GnuCash può essere visualizzata e scaricata dalla pagina della documentazione.

Introduzione

La documentazione di GnuCash è contenuta in file di tipo xml. Più precisamente, utilizza il sistema docbook GNOME2 XML. Questo sistema è relativamente flessibile e partendo dai file xml è possibile generare la documentazione in vari altri formati (html, pdf, ecc...)

Per revisionare o scrivere della documentazione per GnuCash, è necessario conoscere il linguaggio XML. Può anche essere necessaria una conoscenza di base del sistema docbook

I collegamenti seguenti sono relativi ad altri siti che possono essere di aiuto per i processi di creazione e di revisione della documentazione.

DocBook: The Definitive Guide.
DocBook XSL: The Complete Guide.
GNOME Human Interface Guidelines
How_to_translate_the_GnuCash_guide_and/or_help_files: Anche se questa pagina del wiki di GnuCash tratta la traduzione della documentazione, contiene alcune informazioni utili per lavorare con i file docbook.
Documentation_Update_Instructions: Una guida dettagliata su come lavorare con la documentazione (aggiornamento e manutenzione)

Si consiglia anche l'iscrizione a gnucash-devel.

Linee guida di GNOME per la documentazione

Come già detto, la nuova documentazione è basata sul sistema docbook GNOME2 XML. Chiunque desideri contribuire è invitato, dove possibile, a seguire le linee guida al momento della revisione e/o scrittura della documentazione.

Dove ottenere il codice sorgente della documentazione

Sarà necessario ottenere una copia recente del codice sorgente della documentazione. Per farlo è possibile eseguire il "check out" del modulo della documentazione dal repository gnucash-docs. I revisori possono anche iniziare dal pacchetto della documentazione corrente.

Per coloro che non hanno familiarità con git, il wiki di GnuCash ne fornisce una descrizione relativamente al codice di GnuCash. Per ottenere il codice sorgente della documentazione in luogo di quello del programma, sostituire "gnucash" con "gnucash-docs" nei comandi git riportati, come per esempio:

git clone https://github.com/Gnucash/gnucash-docs.git

Esistono due documenti principali di GnuCash per aiutare l'utente: il manuale di aiuto e la guida ai concetti. Con il comando precedente, verrà scaricato il codice sorgente di entrambi.

Autori

Una volta ottenuta una copia del codice sorgente della documentazione nel modo descritto più sopra, sarà possibile iniziare ad effettuare delle modifiche. Una volta soddisfatti dei propri cambiamenti, si potrà creare una patch eseguendo il seguente comando nella cartella base della documentazione (di solito "gnucash-docs", se non è stata rinominata):

git diff > my-patch-name.patch

Allegare poi la patch a una segnalazione di bug relativa al componente "documentazione" per il progetto GnuCash nel database Bugzilla di GNOME e inviare una mail alla lista di discussione gnucash-devel per informare gli altri sviluppatori del proprio lavoro. Consultare anche la pagina del wiki di GnuCash dedicata a bugzilla per maggiori informazioni su come inviare una patch.

NOTA: in passato era sufficiente inviare la propria patch direttamente alla lista di discussione degli sviluppatori. Oggi questo è sconsigliato perché la patch rischia di passare inosservata tra le tante discussioni. Allegare invece la patch a una segnalazione di bug su bugzilla. Se si volesse comunque inviare la patch alla lista di discussione gnucash-devel, si consiglia di allegarla e di non inserirle nel testo della mail.

Si consiglia di comunicare ad altri autori la sezione su cui si desidera lavorare. La richiesta deve essere fatta sulla lista gnucash-devel in modo che le altre persone interessate possano dare il via libera o comunicare che quella particolare sezione è già assegnata a qualcun altro.

Può anche risultare utile mantenere una copia locale della vecchia documentazione come riferimento per la scrittura: essa contiene ancora una grande quantità di informazioni utili che non sono ancora state trasferite nella nuova documentazione.

Revisori

Una volta ottenuta una copia del codice sorgente della documentazione nel modo descritto più sopra, sarà possibile iniziare a commentarla.