[GNC-dev] Long Term Documentation Directions
geert.gnucash at kobaltwit.be
Mon Sep 10 04:48:48 EDT 2018
Op maandag 10 september 2018 10:11:11 CEST schreef David Cousens:
> As well as Frank's objections to rewriting, why does having one massive file
> necessarily improve the structure or maintainability. This is not the case
> with programming code. Docbook can include files in a far more structured
> manner than the gnucash xml sources do at the moment. I would have thought
> more modularization of the documentaion and some restructuring would
> improve the maintainability.
I don't think David T meant to put everything in one single source file. I
believe the idea is to have one single user document. So the user would only
have one link on the website to choose from or one pdf to download to get all
information. Internally this document will certainly still be composed of
multiple source files.
> I think there is perhaps more need for the tutorial approach - "How to do
> this with Gnucash", particularly for newer users ,than for interface
> button by button functional type documentation and the latter is more useful
> when users have gained some experience and just want specific information
> on what happens when they select a particular button or menu option.
I'm a big fan of use-case based documentation (or "tutorial" based). I have no
experience with writing or maintaining such documentation though. I have
attended a couple of presentations earlier this year on that topic. It's much
closer to what users are typically searching for than a formal explanation of
how each feature of gnucash works. Going into this would be a whole
conversation on its own.
But I do follow David T's observation that there's too much duplication. The
fact we currently maintain two fairly independent "manuals" is very likely
conductive to this duplication.
It doesn't necessarily have to be though. If there's a strong definition of
what goes into interface help and what goes into manual we could guard this
The proposal is to make the interface help very short, with links to relevant
topics in the manual. Having links across documents is challenging so I can
follow the proposal to put it all in one document. That will save us support
questions like "the link to topic x in help topic y doesn't seem to work".
> My not particularly deep understanding of docbook is the more the
> documentation is broken down with separate headings the more searchable it
> becomes and the more easily specific information can be located by using a
True. However this is completely tangential to how the sources are split up in
files. This searchability comes from using appropriate tags.
More information about the gnucash-devel