Documentation Regarding GnuCash Import Features

Geert Janssens geert.gnucash at kobaltwit.be
Fri Aug 28 04:03:45 EDT 2015


On Thursday 27 August 2015 15:28:49 John Ralls wrote:
> > On Aug 27, 2015, at 11:30 AM, Geert Janssens
> > <geert.gnucash at kobaltwit.be> wrote:> 
> > On Wednesday 26 August 2015 19:59:59 David T. wrote:
> >> John,
> >> 
> >> I am moving this thread to Devel, since it has moved beyond typical
> >> user threads.
> >> 
> >> Further digging in the Help Manual shows section "3.3. Import QIF
> >> Files," which explains that particular import process, but no
> >> other.
> >> I suspect the interest in putting this information here has to do
> >> with the fact that many newcomers to GnuCash will be importing
> >> their
> >> data from Quicken. However, I think it a little oddly placed and
> >> sadly alone (not to mention hard to find).
> >> 
> >> Additional scanning in the Help Manual (I almost never use it,
> >> alas!)
> >> turns up "Chapter 6. Common Transaction Operations," under which a
> >> section on importing might be placed.
> >> 
> >> As an aside, I will note that this chapter and Chapter 4 of the
> >> Tutorial include largely similar content, and I wonder which
> >> document
> >> would be the better repository for this information. Ultimately, I
> >> believe that one of these chapters should be merged into the other,
> >> and all reference elsewhere should go to the one spot.
> >> 
> >> If a section on importing should be added to the Help Manual, I
> >> would
> >> propose putting it in chapter 6, moving 3.3 into it (with
> >> appropriate
> >> updates), and inserting a general note in 3.3 that discusses
> >> importing in general, and refers readers to the appropriate section
> >> in chapter 6.
> >> 
> >> If instead, it should go into the Tutorial, I imagine it would go
> >> in
> >> either as a new section in Chapter 4, or as a separate chapter
> >> immediately after this chapter.
> >> 
> >> Cheers,
> >> David
> > 
> > Hi David,
> > 
> > I'll first start on the subject of Help vs Tutorial&Concepts guide.
> > This is what I use as guide to choose a document to add some
> > content to:
> > 
> > * The manual ("Help") focuses on what does each aspect of GnuCash
> > do. If I click on this button what happens, what's this menu item
> > for ? Things like that. Technically this is also the document that
> > is referred to when you click the various context help buttons in
> > GnuCash.
> > 
> > * The tutorial and concepts guide on the other hand is focused on
> > how to reach some goal. How to track bank statements, how to track
> > stock investments ? These topics usually mean combining several
> > aspects of gnucash.
> > 
> > I'm aware these guidelines are vague and can even have overlap.
> > Additionally the Tutorial guide starts with very basic topics so
> > users can learn most aspects almost from scratch. Some of the basic
> > topics have a lot of overlap with "what does this or that button
> > do" from the manual.
> > 
> > I think *every* feature of gnucash should ideally be documented in
> > the help manual. However it only needs be done in a very concise
> > style, just enough to explain the use of that particular feature.
> > The guide should be more geared towards getting started with
> > certain tasks. It may or may not cover all features of gnucash. I
> > see it rather task oriented than feature oriented.
> > 
> > I'd love to hear what others use as guide to decide what should go
> > where. Ideally less vague :)
> > 
> > 
> > 
> > As to the other items in your mail: yes the mention of QIF early in
> > the help guide is unfortunate and should be moved to a independent
> > chapter on importing.
> > 
> > To keep the job reasonable I'd agree with John to add it in the Help
> > manual in this case (considering it's first and foremost explain the
> > knobs and buttons of the various import features).
> > 
> > Thanks for spending your time on the documentation. It really needs
> > some love.
> 
> Geert,
> 
> I think of the T & CG as a document for helping people understand the
> principles upon which GnuCash is built: Double-entry and accrual
> accounting, dealing with multiple currencies and commodities, etc.

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.

> or Importing because those don’t really
> need their underlying principles explained. The Help manual should
> indeed explain how everything works in GnuCash, but I don’t think it
> needs to be limited to this-menu-item-does-this-that-button-does-that
> level stuff.
> 
Agreed. That would be too limited. The current help manual has always felt like that though. I'll 
admit I never managed to read through it.

Browsing through it today it still mostly feels like an enumeration of features/menu items 
windows. Note there are almost no screenshots, another indication you are supposed to access 
the help manual by clicking a help button on a specific dialog or search for help on a specific 
menu item (in which case the relevant dialog is already in front of you and a screenshot is not 
needed).

It currently really is a reference manual of what gnucash can do, but much less so on how to 
use it. (And an incomplete one at that - several chapters are placeholders only).

> I wonder if it might be confusing to new users two have two documents
> and how useful or frequently used help buttons are when we also have
> tooltips. Perhaps we should consider combining them into a single
> document with two sections.
> 
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.


More information about the gnucash-devel mailing list