Writing GnuCash Documentation
If you are interested in improving the GnuCash documentation, you have come to the right place. This page will provide you with the necessary information to get started.
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.
The GnuCash community welcomes assistance in maintaining and improving both the program and its documentation. If you are interested in helping write, edit or translate GnuCash's documentation, this page gives guidance on how to get set up to join the effort.
The GnuCash documentation can be viewed and downloaded from the Documentation page.
Introduksjon
The GnuCash documentation is stored in xml files. More precisely, it uses the docbook system. This is a relatively flexible system that takes xml files as input and can generate documentation in several different output formats (html, pdf …).
If you wish to review or write GnuCash documentation, you will need to know xml. Some basic knowledge of the docbook system may be useful as well.
The following links are for further sites that can help with the documentation and review process.
- DocBook: The Definitive Guide
- DocBook XSL: The Complete Guide
- GNOME Human Interface Guidelines
- Translating_the_GnuCash_Guide_and_Help: While this GnuCash wiki page is really about translating the documentation, it holds some useful information on working with docbook files.
- Documentation_Update_Instructions: A detailed guide on how to work with documentation (update and maintenance).
We suggest also subscribing to gnucash-devel.
GNOME-dokumentasjonsretningslinjer
As stated earlier, the new docs are based on the docbook system. Everyone wishing to help please follow these guides where possible when reviewing and/or writing docs.
Where to get the documentation source
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.
Writers
Get a copy of the documentation source as described above and start making changes. When you are satisfied with your changes you can create a patch by running the following command in the base directory of the documentation (usually gnucash-docs, unless you renamed it):
git diff > my-patch-name.patch
Next attach your patch to a bug report against the proper component for the Documentation product in GnuCash' bug database. See also GnuCash' wiki page on bugzilla for more details about patch submission.
NOTE: It used to be ok also to send your patch directly to the gnucash-devel list. This is discouraged now, as a patch is easily forgotten between the many list discussions. Attach patches to bugs in Bugzilla instead (either an existing bug or a new one). If you insist on sending a patch to gnucash-devel, it should be attached, not inlined.
Please let other writers know which section you wish to tackle. Please forward this to gnucash-devel so that people can say 'hey I'm doing that already' or 'go ahead and do it'.
You may also want to retain a local copy of the old documentation to refer to when writing. This still has a lot of useful information in it which hasn't been transferred to the new docs.
Reviewers
Get a copy of the documentation source as described above and start commenting on it.
The best way of retaining comments about docs in an easy to find way for everyone would be to use bugs.gnucash.org to file the bugs under documentation. This can also be done using bug-buddy.
