Documentation Regarding GnuCash Import Features

[John Ralls]

> 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. There’s no chapter on Reports 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.

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.

On a somewhat related topic I noticed that Doxygen can now output DocBook and use Markdown. That might make it easier for the less technically minded to contribute.

Rgards,
John Ralls