Documentation Regarding GnuCash Import Features

[David T.]

> 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…

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

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. 

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

> 
>>  
>> Having said that, I also think combining the two would have some advantages.
>>  
>> Someone would have to do this of course... I fear that a complete overhaul of the documentation would be a huge task. On the other hand no one says it all has to be done in one go.
> 
> Replacing DocBook with Libre/Open Office would both make it easier and get more people to help, but I’ve hived that off to a separate thread. It occurs to me that we might need to keep DocBook for context-sensitive help in Linux. Do we?
> 
> Regards,
> John Ralls
> 
>