[GNC-dev] Documentation Redo

David Cousens davidcousens at bigpond.com
Tue Sep 18 20:16:39 EDT 2018

On Tue, 2018-09-18 at 10:58 -0400, David T. via gnucash-devel wrote:
> Hello,
> Once again, my words have gotten the better of me. I apologize for the length of this message...
> I have to admit that I do not understand what part of this research qualifies it for an IgNobel—was it the “well,
> duh!” aspect, or was it that these folks took seven years to determine this, or was it that they were able to convince
> some funding agency to support it the whole time?
> Setting that aside for a moment, it *is* useful to acknowledge that most people’s help preference is “to click around
> and get help when I need it.” TBH, that’s my style—although once I’ve done that a while, I am quite likely to sit down
> and read in more depth. While I doubt anyone is eager to strip out features from GnuCash (Budgets, anyone?), I think
> we *can* consider that perhaps our assistance modes might need to be reconsidered.
> I have been focused on moving detailed information OUT of Help and putting it INTO the Guide, based on my own
> preferences and experiences with GnuCash. Perhaps that is misguided, insofar as most users aren’t turning to this
> resource consistently.


I spent a lot of time documenting a program a colleague and I wrote in the 1980s for trace element analyis using nuclear
methods on an accelerator for a non-technical user base (largely geologists). We found the most useful way was not to
try and explain the physics and technical details of the process up front, but to give the user a basic process recipe
to follow to achieve the desired outcome and then only provide deeper levels of information as users requested it when
they understood they had a need to know more. We had a captive geologist in our group of physicists who we used as a
test subject (ex Professor of Geology at University of Oslo) to refine our efforts. Geologists at that time generally
didn't have much computing background but knew what they wanted to do whereas we knew how to do things but not why you
would want to (not totally true but enough to make the point). I think there are some analogies to the gnucash user base
and documenters and developers that hold here and it does fit in with the general thrust of the article John referenced.
I access documentation in much the same manner as you. Deeply enough to achieve my current objective and (sometimes)
returning for more depth when required - git/github is a current example there for me.

I think it is possible to build a system with the guide as the primary interface linking to the specific more detailed
"what does this button do" type of information and simultaneously provide a second interface to the same detailed
information which is structured more around the program interface structure linking to the same basic material. To get
that sort of flexibility though you have to invest deeper into the docbook (or similar) technology.

> Assuming that a well-written but overlooked Guide is the proverbial falling tree in the forest, how should we be
> leading the Roaming Clicker to our oasis of Help? I think it is clear from the list traffic that we have quite a bit
> of room for improvement: new users regularly ask for help on topics that have coverage in the Help, the Guide and/or
> the wiki. So, we need to be looking for Something Better.
> Bearing in mind the amount of work already placed in the existing documentation, I believe that we can establish a
> clear Assistance Continuum that uses context help to direct users to specific sections of the Guide. I have
> mentioned  this in other discussions recently, but I want to reiterate it here. We should transition the Context Help
> to contain brief descriptions with a “For more on this topic, see” link to the Guide in every instance. I believe this
> would support the needs of Roaming Clickers reasonably well, using the resources we have already got.
> One major impediment to this is the linking features in our sources. There is little that can be done about this,
> however, short of changing our platform altogether—which past experience shows is doomed to stir up a lot of
> discussion with no ultimate change (“Full of sound and fury” comes to mind). As I see it, one of the major challenges
> in creating links is that we currently have no naming practices for the documents. This causes burdens: which elements
> receive tags? how do we form the names to assign? and on the other side, what name do I need to put in to link to the
> other? If we can establish *what* should get labels, and *how* we label them, I believe it would smooth a great deal
> of this process out. (Even better would be a means to use variables for these, so that references could automagically
> be generated without a user keying in a long link label. How cool would that be?).

docbook at least,  has a structure for addressing this problem. (I haven't looked yet in depth at other possible source
formats like asciidoc or markdown but I would imagine they should also but it may not be as well defined or flexible).
You use aliases much like the id="chapter1" headings in the text that are marked to be exported an xml catalogue file
whch loads into /etc/xml by default  on unix (and similar on windows and Mac OS X which translates the aliases to either
a URI  on a local machine or a url to an online resource like the online form but can be also specified as something
like "/usr/local/share/gnucash/xml/catalogue.xml". It should be possible to automate setting up the links to URI/URL in
the buildto provide an appropriate translation  of links  for the various formats (epub, html, mobi) . Those links can
be internal within a single  document, and/or to other documents as required.

I can invest time in researching and testing how to do this if it is more productive for me to concentrate on doing
this. I don't believe it needs to be in an initial restructure of the guide/ help documents. I think that should
concentrate on organising the guide and consolidating the guide type information in the help manual into the guide (and
perhaps a little vice versa) then in a second pass break out the structure and establish the linkages. 
> The wild card in this Assistance Continuum is the wiki. There is a lot of useful information there; how would a user
> know to find it? Placing an actual link to the wiki is doomed to fail, since the wiki is by nature dynamic. Is there
> some way to add a canned search of the wiki to context help? This canned search would allow the user to retrieve
> information on the wiki as it existed at the time of the search, rather than at the time of the help authorship.

My feeling would be that any information on the wiki which relates to using Gnucash for some specific purpose needs to
be translated into the guide, initially replaced with a link in the wiki to its new location in the guide and eventually
dropped from the wiki as it is difficult to impose a strict structure on the wiki.  The wiki could then be used to
primarily document stuff in development and to make new information available to the user base.  As this "Guide" is
ultimately available on line from the website it should be the primary go to source.  Right up front the Guide, FAQs and
wiki need to be linked
> I imagine here that the Context Help writer would enter a couple of terms into a slot in the Help entry that would
> then be tacked on to a wiki search (and, yes, I am already thinking that a structured storage such as SQL might be a
> better approach to manage this). I will note that such wiki search functionality would of necessity require
> improvement of the wiki search feature, and perhaps a restructuring of how the wiki is created.

I don't think these are under the control of the Gnucash developers - they are wikimedia features. But by understanding
how the wiki search works, it may be better able to structure the wiki so that searches produce better results. My guess
is it should do some tree search crawl of the links but I don't know for sure.

David Cousens


More information about the gnucash-devel mailing list