> On Sep 18, 2018, at 7:58 AM, David T. <sunfis...@yahoo.com> 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. > > 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?). > > 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. > > 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. My attempt > to search the wiki for the entry on adjusting column widths > (https://wiki.gnucash.org/wiki/FAQ#Q:_How_do_I_resize_my_register_columns.3F_Why_can_I_not_shrink_the_description_column.3F) > was less than successful. Any search I entered at the wiki search box > returned a link to the general FAQ page, which doesn’t help. Similar attempts > using Google were unsuccessful as well (why *are* the pdf copies of the > documentation stored on wiki.gnucash.org as well at www.gnucash.org—or are > they the same files?).
Well, the title made *me* laugh, and the paper has clearly gotten us thinking, so it fulfills the IgNobel mission, to identify research “that makes you laugh, then makes you think”. Anyway, on to how to structure the documentation. Links between context help and the Guide should be pretty straightforward, though at present they depend on the DocBook xslt doing the right thing across Yelp, Windows Help, and regular HTML. We might have to tweak the xslt a bit to make sure we get the desired results on all three. IIUC our wiki software (mediawiki) is already built around a SQL database. SQL databases are really good at searching metadata that’s broken out into separate fields and really poor at searching for content within a single field. Articles in mediawiki are stored in a single field, which is why searches suck. The mediawiki folks have given some thought [1] to metadata but there’s no real guidance. A nosql [2] based wiki might well provide better search, but I didn’t find any. I think that leaves us with Google. I have had Google searches return direct links to sections of Wikipedia pages (the headline link is the page, but underneath there will be a link called “jump directly to <section name>”). We'd need to figure out how to make that work on our wiki. The problem with a search-based solution is that the results are non-deterministic. We could include a “Search the GnuCash Wiki for foo” link on every context help item, but there’s no guarantee that searching for foo will actually find anything and even if it does that any of it will be relevant to the context help item... though we might be able to increase the odds by somehow tagging articles or article anchors with the context-help topic. We’d need a way to make sure that those tags stayed current and correct. While we’re at it we should consider making more concrete the separation between “Tutorial” and “Concepts Guide” and I suppose decide how to host each and how much detail to incorporate in the latter. To elaborate, I don’t think we want to write our own accounting textbook. There are plenty out there already, written by people with much better understanding of the subject and better writing skills. We do want to explain why GnuCash is based on accounting and why a prospective user needs to understand it at at least the Accounting-101 level. Beyond that I suppose Concepts Guide part would explain how GnuCash implements various accounting principles and the underlying data structure and terms. Regards, John Ralls [1] https://www.mediawiki.org/wiki/Page_metadata <https://www.mediawiki.org/wiki/Page_metadata> [2] https://en.wikipedia.org/wiki/NoSQL _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
