GNOME Bugzilla – Bug 621573
Description of splits
Last modified: 2018-06-29 22:40:56 UTC
I have followed "GnuCash Tutorial and Concepts Guide" . (or tried) My attempts at creating splits have not worked correctly. I think it would be helpful to decompose the process more.
Thanks for taking the time to report this bug. This bug report isn't very useful because it doesn't describe the bug well. If you have time and can still reproduce the bug, please read http://bugzilla.gnome.org/bug-HOWTO.html and add a more useful description to this bug.
The recommended place for documentation suggestions was to file a bug report. As I do not understand creating split transactions, I can not say what must be described and is not. If you have more specific questions, perhaps I can answer.
Hi teidooricaerak, I want to help fix this if I can. Could you confirm which section of the Guide we are talking about here? My guess is `4.2.2 Split Transaction', is this correct? In either case, could you point out the parts of the explanations which are unclear, and why? Even short reasons in point form would be helpful here. With this information, it should be easy to rewrite the section in a clearer way. Thanks again for taking the time.
I don't know the OP's issues, but I suggest at least the following minor changes to 4.2.2, paragraph 2: To add a paycheck transaction from the Assets:Checking account register window, click on a new transaction line, and click on Split. First enter the description of this transaction on the first line (e.g. "Employers R Us").* In the split line below this, enter the amount that is being deposited into the current account (e.g. $670 into Assets:Checking). Follow this by entering the amounts for the various taxes--for example, Expenses:Taxes:Federal, $180; Expenses:Taxes:Medicare $90; and Expenses:Taxes:Social Security, $60. Finally, enter the gross total of your paycheck ($1000 in this example) as a withdrawal transfer from Income:Salary. The final split should look like this: * Note: I removed a comment about a current bug that doesn't seem current any more, as I was able in 2.2.9 to enter a split for a different account without trouble. If the comment is still needed, it should read: (Due to a bug in version x.x.x, the first line in a split must use the current account) Further editorial note: the use of "eg" stylistically includes periods, since this is an abbreviation of the latin phrase "exempli gratia", as in "e.g." "For example" is a reasonable English substitute. Similarly, "i.e." for "id est", which can be changed to "That is"
Created attachment 173372 [details] [review] Fix #621573 David, I believe this is a good start. Completely agree about the reference to the non-existent bug and the e.g. periods. Attaching a candidate patch here that I should be able to commit soon barring any silly mistakes.
Comment on attachment 173372 [details] [review] Fix #621573 Shouldn't the text also mention to choose the respective accounts in the corresponding line of the split?
Christian, 4.2.1 (immediately preceding this section) covers selecting an account. Is more needed? Should there be more of an explanation about what you are doing when you select an account for the split? I will note that 4.1 offers definitions for these concepts. It is not clear to me what is served by having separate sections for 4.1 and 4.2, except a standard chapter structure. In this case, the two sections are intimately intertied, and having a separate page for "Basic Concepts" here interrupts what would be a very clear progression of ideas.
I think the comments made in a new bug (633385) should be folded into this task and 633385 should be closed. The points in 633385 are well taken and should be considered. The description of splits is part of ch_basics.xml, which I am working on. The accounting concept of 'split' should be part of the basics chapter where all accounting concepts used by GnuCash should reside. The Chapter 4 part of the Guide can cover the mechanics of using splits inside GnuCash, which it does now. Putting concepts in the basic chapter will enable us to streamline the Guide by removing duplication. Where an application of concepts (splits in chapter 4) is described, it can like back to the basics chapter for definitions and explanations in case the reader does not remember clearly what the meanings of the terms are. Any thoughts from anyone?
(In reply to comment #8) Dave elaborates his thought in 633385. Keeping this bug to focus on chapter 2 issues and bug 633385 to focus on chapter 4 will be better from a flexibility and and work flow standpoint. The overlap he notes will persist until both chapters 2 and 4 are corrected to remove what he is noticing.
(In reply to comment #7) > Christian, 4.2.1 (immediately preceding this section) covers selecting an > account. Is more needed? Should there be more of an explanation about what you > are doing when you select an account for the split? I tend to agree with Christian here, it may not be immediately obvious to a new user that the way to enter a multi-split transaction differs from entering a simple transaction. Ideally, I'd like to introduce just a couple of keyboard shortcuts (Tab, Shift-Tab, Up/Down, Enter) at the beginning of §4.2, just so we can tell the user to `tab over the Transfer field and choose an account from the drop-down'. > I will note that 4.1 offers definitions for these concepts. It is not clear to > me what is served by having separate sections for 4.1 and 4.2, except a > standard chapter structure. In this case, the two sections are intimately > intertied, and having a separate page for "Basic Concepts" here interrupts what > would be a very clear progression of ideas. Maybe this section can talk a little bit about what the traditional general ledger posted transaction looks like, and then entice the reader by saying that GnuCash makes it a lot simpler ... :-) In any case, that is probably best served as the sole focus of another, new, bug. I can open a new bug by tomorrow evening because I'm planning to spend some time this evening working on existing bugs. If you or someone else beats me to it by then, well and good :-)
Wouldn't 633385 be that new bug? If not, what do you have in mind that differs?
(In reply to comment #9) > (In reply to comment #8) > > Dave elaborates his thought in 633385. Keeping this bug to focus on chapter 2 > issues and bug 633385 to focus on chapter 4 will be better from a flexibility > and and work flow standpoint. > > The overlap he notes will persist until both chapters 2 and 4 are corrected to > remove what he is noticing. Actually, I view this bug covering chapter 4, and the other covering chapter 2...
Hi Tom, (In reply to comment #11) > Wouldn't 633385 be that new bug? If not, what do you have in mind that > differs? See #633524 for my thoughts on this. Thanks
Created attachment 173544 [details] [review] Fix #621573 Simplify explanation of entering a split transaction and remove comment about register bug (no longer applicable). Separate the explanation into paragraphs covering the mechanics, the specific example, and the outcome. Also, refer to the screenshot through a DocBook xref tag for general portability, and remove the redundant screenshot caption.
(In reply to comment #13) > Hi Tom, > (In reply to comment #11) > > Wouldn't 633385 be that new bug? If not, what do you have in mind that > > differs? > > See #633524 for my thoughts on this. > > Thanks I guess what I should say to both you and the others in the comment thread is that I think the documentation should develop whatever is necessary to explain concepts and in sections separate from the concepts explain their application and how GC implements them so that the user can actually use the feature. For me the conceptual development should all be in the basics chapter of the Guide. Following the concepts in the same or other chapters comes the explanation of how the concepts are implemented in GC in sufficient detail for the user to understand and use the feature. From the number of emails I have received in the last two days it is clear that much work on a number of bugs is going on. It is secondary to me which bug does what, as long as what is going on in which bug is clear to all. Since you are the GC developer and heavily involved in laying out work plans, I am glad to pursue the directions you are laying out. For those with more experience in using GC and its documentation the scope of any bug might be more immediately evident. It is not so for me always. If it is not too much trouble for the person working on a bug, I think it would be helpful (in the comment following a problem definition/announcement) to spell out what will be done in which bug. Sometimes a reporter can state a problem based on what he sees that seems to be one issue but actually could be more than one. The problem fixer should decide which problem is being fixed in which bug. If that were to happen, then others would see the problem's complexity. It would also give the reporter to affirm the problem seems to be handled fully or that there were other aspects to include. HTH
(In reply to comment #15) > (In reply to comment #13) > > Hi Tom, > > (In reply to comment #11) > > > Wouldn't 633385 be that new bug? If not, what do you have in mind that > > > differs? > > > > See #633524 for my thoughts on this. > > > > Thanks > Just as a PS to comment 15, bug 633524 as a new item is the sort of thing I am thinking about. It succinctly states the scope of work intended for that bug.
Hi Tom, (In reply to comment #15) > [...] > For me the conceptual development should all be in the basics chapter of the > Guide. Following the concepts in the same or other chapters comes the > explanation of how the concepts are implemented in GC in sufficient detail for > the user to understand and use the feature. As to that, the way I've always understood the guide is that it's trying to present concepts and tutorials in easily-digestible chunks, so that the reader isn't overwhelmed first by a wealth of abstract information, and then by a flood of step-by-step instructions. For example, I recently bought O'Reilly's Version Control with Git and have been reading through it. What I was impressed by is the gentle way in which important concepts and internal structures are introduced. If you look through the table of contents [1] you see almost invariably each chapter starts with concepts, and then shows practical uses. > Since you are the GC developer and heavily involved in laying out work plans, I > am glad to pursue the directions you are laying out. For those with more > experience in using GC and its documentation the scope of any bug might be more > immediately evident. It is not so for me always. I feel your pain there :-) Even as the progenitor of some of these `bugs' I myself have a hard time keeping them straight because some of them are so interlinked. BugZilla has a feature where you can say that bug A `depends on' bug B, meaning B has to be fixed before A, but I myself am pretty new at this and am still learning to structure bugs with the system. So it's a learning curve for all of us. > If it is not too much trouble for the person working on a bug, I think it would > be helpful (in the comment following a problem definition/announcement) to > spell out what will be done in which bug. Usually I think the best way to spell out what should be done is to just attach a patch to the bug report or for less technical people just type out the desired text (as David has been doing recently). Then others can review and suggest improvements/cuts/whatever. The point is someone should get the ball rolling. Even if not immediately, then at some time after reporting the bug. And to anyone who does this, they have my profuse thanks :-) > Sometimes a reporter can state a > problem based on what he sees that seems to be one issue but actually could be > more than one. The problem fixer should decide which problem is being fixed in > which bug. If that were to happen, then others would see the problem's > complexity. It would also give the reporter to affirm the problem seems to be > handled fully or that there were other aspects to include. Yes, this is the case for structuring bugs with BugZilla's `depends on' feature. It's a relatively easy way to make explicit what has to be done and in what order. Thanks for your thoughtful comment. [1] http://oreilly.com/catalog/9780596520137/
This fix is an attempt to decompose the split creation process a little bit, as the original bug reporter suggested. Not being able to get in touch with him/her, I don't know how close it comes to satisfying that requirement, but am closing this--at least for now. In future we can reopen, for example, if we decide to coordinate this description with that in the Help Manual.
GnuCash bug tracking has moved to a new Bugzilla host. This bug has been copied to https://bugs.gnucash.org/show_bug.cgi?id=621573. Please update any external references or bookmarks.