Documentation Regarding GnuCash Import Features

[Geert Janssens]

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 :)