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 _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
