Documentation Regarding GnuCash Import Features

[John Ralls]

> On Aug 28, 2015, at 10:56 AM, Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
> 
> On Friday 28 August 2015 09:07:09 David T. wrote:
> > > On Aug 28, 2015, at 4:54 AM, John Ralls <jralls at ceridwen.us> wrote:
> > >> On Aug 28, 2015, at 9:03 AM, Geert Janssens
> > >> <geert.gnucash at kobaltwit.be <mailto:geert.gnucash at kobaltwit.be>>
> > >> wrote:
> > >>
> > >> That's interesting: your focus appears to be on the "Concepts"
> > >> aspect of "Tutorial and Concepts Guide". My focus was rather on
> > >> "Tutorial". I guess the name itself is already ambiguous.>>
> > >> > There’s no chapter on Reports
> > >>
> > >> You're right there is no separate chapter on reports, but reports
> > >> are touched regardless as part of several tutorials. For example
> > >> 4.7.5 talks about the cash flow and transaction report. 5.5.5
> > >> covers reports relevant to checkbook management, 6.5.8 is about
> > >> credit cards, and so on.
> > >>
> > >> That's what I meant with each tutorial brings together many
> > >> features of gnucash, instead of explaining each in isolation.>
> > > Fair enough. Let’s turn the T&CG into the GnuCash Manual, with three
> > > sections: Concepts, Task-oriented tutorials, and Feature
> > > descriptions (not necessarily in that order).
> > With regard to the issue of reports documentation, I’ll note that bug
> > 633590 has been Out There for a while, languishing. Maybe I will have
> > another crack at it…
> >
> I had forgotten about that one. I have added my feedback on the bug itself.
>  
> > As for the more fundamental rearrangement you mention, I think that
> > would be excellent, although to my mind the sequence might better be
> > Concepts, Features, and Tutorials (moving from intangible to
> > concrete).
>  
> I'm not sure. For me the "features" part sounds more like a reference guide, which is usually in the end. Tutorials on the other hand help you get started without having to read the whole guide. However I'm not
>  
> > Considering the current Guide, though, I wonder if it
> > might not be enough just to put the Tutorials in a separate section;
> > most of the guide at this point mixes Concepts and Features
> > liberally, and teasing them apart would entail essentially a full
> > rewrite. I am not sure anyone has that much gas.
> >
> Completely agreed.
>  
> > Bug 687820 was a suggestion on my part to restructure the guide; I
> > think that my goal was something more in line with this broader
> > arrangement, although it would need further refinement to fully
> > realize the separattion you suggested.
>  
> Another bug I had forgotten about. It's a good basis to discuss future structure on. Given the limited manpower I would also propose to work in small steps towards the bigger end goal where possible. That should help everybody to keep sufficient gas as you so nicely put it.
>  
> <snip>
>  
> > >> I have no idea how frequently the help buttons would be used. I do
> > >> remember seeing bug reports in the past because some buttons were
> > >> not working. So at least *some* people look at them.>
> > > So maybe we should focus the help on context-sensitive help and stop
> > > trying to publish it as a book.
> > I think this is the way to move forward.
> >
> > Perhaps the context help could focus primarily on
> > this-menu-item-does-this-that-button-does-that but include references
> > into the (single) Manual for further assistance. That way, the
> > documentation team (such as it is) can direct its efforts to ensuring
> > that the Manual is the completest bestest Manual there ever was.
>  
> We may be having some impedance mismatches here.
>  
> So to be clear: the current context help is part of the help document we have now. So I presume it will also be part of the future unified manual ? Is that what is referred to as "features" in the discussion above, or did you see this as a separate (and very concise) section of the manual with features a more detailed description of everything gnucash has to offer ?
>  
> Perhaps the discussion is just too abstract for me and some concrete examples of each kind of information we want to offer would help clarify things.
>  
> Regards,
>  
> Geert
>  
> P.S. I expect that John will also give his input still, but he's currently in the air somewhere on his way home. Let's just give him some time to come out of jet lag :)

Back home now.

I have no particular attachment to the order of the sections in the main manual, and I think having references/hyperlinks between the context help and the manual is an excellent idea.

As for what-goes-where, the context help needs to be set up in  a way that it gets served when the help button is pushed. How it gets served is another matter entirely. I never mustered the will to create a Mac-help formatted help manual so there the help button opens the linked section in the default browser. I’ve occasionally thought that it would be nicer to make it display in an html tab since we have that capability, but never assigned it a priority. 

In my view a context help should answer the question “So I’ve opened this Edit Account dialog box. Now what?” It should point out the important things in the dialog: The name, symbol, security, type, and parent controls. It can link to a tutorial on how to set up an account hierarchy, to a concepts article that describes the different account types and what they’re for, and so on.

Regards,
John Ralls