[GNC-dev] Long Term Documentation Directions

[Geert Janssens]

Op maandag 10 september 2018 10:11:11 CEST schreef David Cousens:
> David,
> 
> 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 
off.

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

True. However this is completely tangential to how the sources are split up in 
files. This searchability comes from using appropriate tags.

Regards,

Geert