sunfish62 at yahoo.com
Tue Jan 27 22:02:31 EST 2015
Thanks for your input.
As I look at this in greater detail, I see that this bug, combined with my own recommendations in bug https://bugzilla.gnome.org/show_bug.cgi?id=687820 point toward a bigger rewrite. Looking the two bugs over (along with the interlinked bugs mentioned in the comments of the latter bug), my preference would be to work up an extensive update to many chapters of the Guide.
My question is this: assuming that I succeed in tackling the DocBook Dilemma, at what level should I submit bugs and/or patches? At the chapter level? At section levels? Should each patch go into a separate bug, or should they all be entered under one of these two bugs?
From: John Ralls <jralls at ceridwen.us>
To: David T. <sunfish62 at yahoo.com>
Cc: Gnucash-devel <gnucash-devel at gnucash.org>
Sent: Monday, January 26, 2015 10:17 PM
Subject: Re: Bug 634181
> On Jan 26, 2015, at 7:00 PM, David T. <sunfish62 at yahoo.com> wrote:
> I was looking through the open list of Documentation bugs that John linked to before the last major release, and took a look at the above bug.
> The bug recommends structuring the Concepts guide to follow the overall structure outlined in Section 1.3 "About This Book".
> There are a couple of points about this bug.
> First, it seems to me that the original portion of the bug could be addressed by adding a one sentence summary to each chapter listed here. This would assist users in finding the material most germane to their need for guidance. If others agree, I could provide those sentences, and this bug could be closed.
> Second, the only comment on the bug raises an important aspect of the software that isn't really well-addressed anywhere in the documentation--specifically, the differences between personal use and business use, and how to determine where that line gets drawn.
> This lack of delineation crops up somewhat regularly on the user list. Questions on how to use Gnucash for personal use get answers from a business perspective, and vice versa with striking frequency. It seems to me that most requests for help on the list have to negotiate this distinction. By finding a way to bring the concept of Business vs. Personal Use more to the forefront, it might at least get new users thinking about this before they send in their request for help, which in turn would allow list users to hone in on the right solution to the problem at hand.
> Looking at the Tutorial documentation, it seems to me that the appropriate spot for this would be in Chapter 1. I believe that the first few sections of Chapter 1 should be extensively rewritten to make them more formal--and while that was taking place, I would strive to include this distinction. I am neither an accountant nor a business user of Gnucash, however, and so any discussion I would provide would be superficial at best, and misleading at worst.
> If there is general agreement with this direction, I would:
> 1) Add chapter descriptions for section 1.32) Spin off the Business vs. Personal ideas as a new documentation bug, and3) Begin work on a rewrite that incorporates any discussion and insights that the developers have in regards to the Business vs. Personal use issue.
That sounds great, with one question: Are you able to write proper DocBook patches? That was the big blocker to getting documentation contributions the last time it came up here, and it's still unresolved except for those who are willing to dive in with a plain XML editor or to work with the foibles of the one extant free (unfortunately only as in beer) DocBook editor.
More information about the gnucash-devel