Re: [GNC-dev] Documentation Redo

[David Cousens]

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.

David,

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 

Re: [GNC-dev] Documentation Redo

[Frank H. Ellenberger]

Am 18.09.18 um 16:58 schrieb David T. via gnucash-devel:
> 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 don't know off hand, but we can at least add the following and could
probably add menu point in gnucashs help menu :
>From 8f3d722a8830394e8916fc2a72ba4a8e3a17445c Tue, 18 Sep 2018 20:38:08
+0200
From: Frank H. Ellenberger 
Date: Tue, 18 Sep 2018 20:36:37 +0200
Subject: [PATCH] Add Wiki Search page to Getting Help

diff --git a/help/C/Help_ch_GettingHelp.xml b/help/C/Help_ch_GettingHelp.xml
index d940810..5e5a659 100644
--- a/help/C/Help_ch_GettingHelp.xml
+++ b/help/C/Help_ch_GettingHelp.xml
@@ -115,6 +115,8 @@
  Questions page should be a first stop whenever you
  encounter difficulty using
  .
+ You should also try its
+ https://wiki.gnucash.org/wiki/Special:Search;>search
page





___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation Redo

[John Ralls]

> On Sep 18, 2018, at 7:58 AM, David T.  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 

Re: [GNC-dev] Documentation Redo

[David T. via gnucash-devel]

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?).

Cheers,
David

> On Sep 16, 2018, at 11:11 PM, John Ralls  wrote:
> 
> So the IgNobel Prizes are out, and the “winner" of the literature prize is
> "Life Is Too Short to RTFM: How Users Relate to Documentation and "Excess 
> Features in Consumer Products”, 
> https://academic.oup.com/iwc/article/28/1/27/2363584 
> .
> 
> Maybe instead of doing a rewrite we should just bin the lot and put the 
> effort into stripping GnuCash down to the bare essentials.
> 
> 
> ;-)
> 
> Regards,
> John Ralls
> 
> 
> 

Re: [GNC-dev] Documentation Redo

[David Cousens]

This paragraph is fairly instructive though.

"When reading to do, people seek information that helps them to conquer their 
goals/tasks. Help systems that use reading
to do are more likely to help users reach their goals (Varland and Svensson, 
2006). However, people often do not learn
how to read to do, and many authors of manuals do not write for reading to do."

My experience in education is that for some people learning is a kinesthetic 
thing - they have to do to learn. 15 % of
the population are generally primarily kinesthetic learners, 25% primarily 
auditory and 30% primary visual learners. The
remainder of us utilize a mixture of styles.

David Cousens


On Sun, 2018-09-16 at 20:11 -0700, John Ralls wrote:
> So the IgNobel Prizes are out, and the “winner" of the literature prize is
> "Life Is Too Short to RTFM: How Users Relate to Documentation and "Excess 
> Features in Consumer Products”, https://acad
> emic.oup.com/iwc/article/28/1/27/2363584 
> .
> 
> Maybe instead of doing a rewrite we should just bin the lot and put the 
> effort into stripping GnuCash down to the bare
> essentials.
> 
> 
> ;-)
> 
> Regards,
> John Ralls
> 
> 
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: [GNC-dev] Documentation Redo

[Adrien Monteleone]

Seeing the changes from Gnome2 to Gnome3, particularly with respect to 
Nautilus, I suspect whomever is in charge of the Gnome HIG is very familiar 
with that research...

Regards,
Adrien

> On Sep 16, 2018, at 10:11 PM, John Ralls  wrote:
> 
> So the IgNobel Prizes are out, and the “winner" of the literature prize is
> "Life Is Too Short to RTFM: How Users Relate to Documentation and "Excess 
> Features in Consumer Products”, 
> https://academic.oup.com/iwc/article/28/1/27/2363584 
> .
> 
> Maybe instead of doing a rewrite we should just bin the lot and put the 
> effort into stripping GnuCash down to the bare essentials.
> 
> 
> ;-)
> 
> Regards,
> John Ralls
> 
> 
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

[GNC-dev] Documentation Redo

[John Ralls]

So the IgNobel Prizes are out, and the “winner" of the literature prize is
"Life Is Too Short to RTFM: How Users Relate to Documentation and "Excess 
Features in Consumer Products”, 
https://academic.oup.com/iwc/article/28/1/27/2363584 
.

Maybe instead of doing a rewrite we should just bin the lot and put the effort 
into stripping GnuCash down to the bare essentials.


;-)

Regards,
John Ralls


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel