[GNC-dev] Long Term Documentation Directions

Mon Sep 10 11:26:44 EDT 2018

Dear All,

I reply to this message (even though it lacks the previous discussions for context), as it is the latest in the thread. I will, however, try to take on some of the issues that have gotten raised. I apologize for the length and density of the reply.

With regard to translations, I am not informed enough of any of the issues involved to offer any insight. I defer to those who can speak more than one language using complete sentences (rather than a combination of misconjugated verbs, incorrect formality modes, and gestures not intended to be rude in any way). ;)

With regard to the idea of using multiple back end XML files, Geert is right that I was not talking about removing multiple back end source files (although I will note that having data fragmented in the sources seems to lead to duplication of content and effort, as different writers conceptualize the proper location for a given piece of information in different ways). My goal is to unify the narrative help into one sequence and reduce duplication and overlap. Bringing all the source XML files into one Frankenstein sequence might be a way to see the future pain, but I imagine that any such amalgamation would only exist for the editorial process; any final product would in all likelihood bear only limited similarity to this documentation monster.

As might be expected from my sending in a generic bombshell, there has been a lively discussion touching on a number of different aspects of the documentation.

At the core, my proposal has the goal of making clearer the primary purposes of the different types of documentation, and working to ensure that information gets placed in the proper place, and only the proper place. 

The article at https://pronovix.com/blog/overview-context-sensitive-and-embedded-help-formats <https://pronovix.com/blog/overview-context-sensitive-and-embedded-help-formats> focuses on web modalities, but the background analysis of user assistance-seeking behavior is intriguing.

Currently, there is a lack of clarity in the GnuCash community on the roles of the different documentation, and it crops up repeatedly. Questions of appropriate content for the wiki, of whether information belongs in the Help or the Guide, etc. are all indicative of this underlying problem.

*** My Documentation Manifesto ***
1. The Concept Guide should be the primary informational document. 
2. The Help should provide specific information on the functions that a given on screen element serves—i.e., Contextual Help.
3. The wiki should give technical information and information that is only applicable to specific user situations.

With these three statements, a number of results follow. 

First, the Guide would contain most of the narrative, explanatory text covering how GnuCash works, and how to manage most common accounting situations. Next, the Help would be stripped back substantially, with most of the narrative content that currently resides in the Help migrated to the Guide. Third, the Tutorial aspects of the documentation would reside on the wiki. More on the Tutorial issue later.

My goal is to eliminate the situation where we document Online Banking [or Reconciliation, or Account Types, or Loans, or Investments, or… you get the idea] in every spot in the GnuCash documentation, and, just for fun, have each one differ just a little bit from the others, so that the user can’t be sure which source is the closest to accurate. 

With regard to the Help, I wonder whether there is some way to use the code itself to generate context help programmatically, rather than have it be a human-edited, git-managed document. As it stands right now, the Help kind of looks like someone started out that way with lists of menus and options, but then someone else came along and started writing text to go with those lists of menus. And now we have something in between. Having a programmatically-generated Context Help system would remove this document from the concerns of documenters, and once established, would only need modification if the interface were changed. I do not know how such a mechanism would work, but I imagine that it would require additional work in code to ensure that the proper links are embedded. I recognize that such an endeavor would be substantial for an application as complex as GnuCash, but I believe the payoff would be major.

Returning to the Tutorial issue: Geert asked me whether it was the style of the writing, or the content that bothered me. I think that the style was what first bothered me there, but as I considered it further, I felt that there were deeper issues embedded. Most fundamentally, I think that as currently written, some information about how GnuCash works is written in the *Guide* parts of the T&CG, while other aspects are embedded in the *Tutorial* parts of the T&CG. See, for example, section 3.3 of the Guide, which includes account setup information that is largely duplicated in the Help at Chapter 5, but is nowhere else in the Guide. The rest of the Guide chapter leading up to this Tutorial is all theoretical, and there is nothing else in the Guide that covers the Account creation process. This, to me, does not make sense, and will lead to an incomplete understanding of GnuCash’s features and functions. It would be preferable to have the Guide outline these features in one sequence. It is my belief that a clearly-written Guide would in fact obviate the need for much of the content currently embedded in Tutorial sections.

I would MUCH prefer to have Tutorial aspects removed from the Concept Guide altogether, and have them placed somewhere else. Since a tutorial, of necessity, is more situationally-focused, I recommend putting this information on the wiki. Establishing the wiki for this information might lead to a number of such contributions to be placed there (where the burdens of git and version control are removed). The wiki could contain a much broader, richer set of tutorials that cover many more use case scenarios. Much of this sort of information could come from the lists, where users over the years have hammered out solutions to specific situations, which don’t belong in a Guide or Help, but which would be useful to a subset of GnuCash users. Handling Expense reports, managing retirement funds, addressing VAT—all could be presented on the wiki. This could also help users on gnucash-users, since so many of the questions come up cyclically (how do I handle taxes?, should I close my books?); such situations could quickly be addressed by directing the new users to the wiki page, instead of re-litigating every aspect of accounting history with regards to book closing (for example).

The idea of use-case recipes sounds rather like the “walkthrough" described in the pronovix article, which they clearly see as a specific, separate, experience. Such resources have their place, but not in the Concept Guide. Walkthroughs could use DocBook ENTITY mechanisms to cobble together snippets of steps into a single sequence, but that makes my head hurt, so I won’t be the one taking that project on.

David T.

> On Sep 10, 2018, at 9:11 AM, David Cousens <davidcousens at bigpond.com> wrote:
> 
> Geert
> 
> Docbook has a mechanism for including other xlm files either by declaring an
> ENTITY which maps on to the filename containing the snippet xml code. You
> can then use &<entity-name> to include the file contents at any point. You
> can also construct "header files" which contain the entity definitions which
> can be included in files as required. There is another mechanism using
> XInclude which apparently has some more desirable traits. I found a Stack
> exchange post/article on it today which extolled the virtues of usng
> Xinclude. I'll find it again and post a link.
> 
> The current source files could be easily merged into the one document as
> each file in the two documents has an entity declared. By moving the entity
> declarations from the Guide to the Help manual and similarly moving the
> &entity-name> lines in the gnucash-guide.xml  into the gnucash-help.xml file
> then moving the Guide source files in with the Help source files, they would
> become one document (needing some major rearrangement of course).
> 
> An initial rearrangement looks possible by just rearranging the order of
> the &<entity-name> statements. At the moment each file is a chapter and is
> imported by the above statements.
> 
> A full rearrangement would require breaking the chapters  down into snippets
> and then including them where required or in some cases just providing a
> link back to where the snippet is first included.
> 
> David Cousens
> 
> 
> 
> 
> -----
> David Cousens
> --
> Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-Dev-f1435356.html
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel