GnuCash-documentatie schrijven
Als u geïnteresseerd bent in het verbeteren van de GnuCash-documentatie, bent u hier aan het juiste adres. Deze pagina verschaft u de nodige informatie om te beginnen.
Just as the GnuCash application has been developed over time by volunteers, so too has the documentation been written by volunteer developers and users to help others learn how GnuCash works. This collaborative effort has resulted in the creation of two major documents, the Help Manual and the Tutorial and Concepts Guide.
De GnuCash-gemeenschap verwelkomt hulp bij het onderhouden en verbeteren van zowel het programma als de bijbehorende documentatie. Als u geïnteresseerd bent in het helpen schrijven, bewerken of vertalen van de documentatie van GnuCash, helpt deze pagina u op weg om mee te doen.
De GnuCash-documentatie kan worden bekeken en gedownload van de Documentatie- pagina.
Introductie
De GnuCash documentatie wordt opgeslagen als XML-bestanden. Meer specifiek: de documentatie gebruikt het GNOME2 XML docbook-systeem, een relatief flexibel systeem dat op basis van XML-bestanden documentatie in verschillende vormen (html, pdf, ...) kan aanbieden.
Als je wil helpen met het schrijven of reviewen van GnuCash documentatie, zal je eerst met XML overweg moeten kunnen. Elementaire kennis van het docbook-systeem kan ook handig zijn.
De volgende koppelingen verwijzen naar overige sites die kunnen helpen bij het documentatie- en reviewproces.
- DocBook: The Definitive Guide.
- DocBook XSL: The Complete Guide.
- GNOME Human Interface Guidelines
- How_to_translate_the_GnuCash_guide_and/or_help_files: Hoewel deze GnuCash wiki-pagina eigenlijk over het vertalen van de documentatie gaat, staat er ook nuttige informatie in over het werken met docbook-bestanden.
- Documentation_Update_Instructions: Een gedetailleerde handleiding hoe om te gaan met documentatie (bijwerken en onderhoud)
Ook adviseren wij u zich te abonneren op gnucash-devel.
Documentatierichtlijnen van Gnome
Zoals eerder vermeld is de nieuwe documentatie gebaseerd op het GNOME2 XML docbook-systeem. Iedereen die wil helpen met het schrijven en/of reviewen van de documentatie verzoeken wij om deze richtlijnen waar mogelijk te volgen.
Waar vind ik de documentatiebestanden
You will need a recent copy of the documentation source. For this you can check out the documentation module from the gnucash-docs git repository. Reviewers could also start from the current docs tarball.
For those not familiar with git, the GnuCash wiki has a description tailored to the GnuCash code. To get the documentation source instead of the program source, replace 'gnucash' with 'gnucash-docs' in the mentioned git commands, like this:
git clone https://github.com/Gnucash/gnucash-docs.git
There are two major GnuCash documentation packages to help users: the Help Manual and the Tutorial and Concepts Guide. With the above command, the source code of both will be downloaded.
Schrijvers
Maak een eigen kopie van de documentatiebestanden zoals hierboven beschreven en pas deze aan. Als je tevreden bent over de wijzigingen maak je een patchbestand door het volgende commando uit te voeren in de basismap van de documentatie (normaal gesproken gnucash-docs, tenzij je de naam hebt gewijzigd):
git diff > my-patch-name.patch
Vervolgens hang je de patch als bijlage aan een bugrapport voor de component "documentation" van het project GnuCash in de Bugzilla-databank van GNOME. Tot slot stuur je een berichtje naar de gnucash-devel mailinglijst om andere ontwikkelaars op de hoogte te brengen van je werk. Voor meer details over het inzenden van patches kan je ook deGnuCash wiki pagina over Bugzilla doorlezen.
Opmerking: Hoewel dit vroeger gebruikelijk was, wordt het tegenwoordig afgeraden om je patch rechtstreeks naar de gnucash-devel mailinglijst te sturen. Door de patch aan een (nieuw of bestaand) bugrapport in Bugzilla te hangen wordt voorkomen dat de patch zoekraakt tussen alle discussies op de lijst. Als je er echt op staat om de patch naar de mailinglijst te sturen, doe het dan als bijlage, niet in de tekst van de e-mail zelf.
Laat ook aan andere schrijvers weten met welke sectie je aan de slag gaat door een e-mail te sturen naar gnucash-devel. Op die manier kunnen we dubbel werk zoveel mogelijk voorkomen.
Het is wellicht ook interessant om een lokale kopie te bewaren van de oude documentatie om dingen op te zoeken tijdens het schrijven. Deze bevat nog veel nuttige informatie die niet overgenomen is in de nieuwe documentatie.
Reviewers
Maak een eigen kopie van de documentatiebestanden zoals hierboven beschreven en begin met het leveren van opmerkingen.
Deze opmerkingen moeten natuurlijk zodanig bewaard worden dat ze voor iedereen makkelijk terug te vinden zijn. De beste manier om dit te doen is om deze als bugreports in te dienen op bugzilla.gnome.org (categorie: 'documentation'). Dit kan ook via het programma Bug-buddy.