GNOME Bugzilla – Bug 633385
Concepts Guide Section 2.2 and 4.2 Overlap
Last modified: 2018-06-29 22:46:18 UTC
Section 2.2 Data Entry Concepts includes an in-depth explanation of entering transactions that is largely duplicated in 4.2 The Account Register. I like the depth of explanation of splits in 2.2. However, the discussion somewhere crosses over from a conceptual discussion of data entry into the specifics of entering a transaction. The upshot is that 2.2.2 duplicates 4.2.2 to an extreme degree. 2.2.2 should be truncated after the second paragraph, and the remaining content there moved to 4.2. It might be useful to flesh out the discussion of double entry bookkeeping here, but keep the actual register/splits discussion elsewhere.
Please see bug 621573, which talks about the cleaning up the documentation and making the explanation of splits more clear and understandable. I recommend that these thoughts be transferred there and this bug closed. Any other thoughts?
I created this bug in direct relation to 621573. You will see that I put forth the new language for 4.2.2. In the course of addressing Christian's comment, i noticed the problem outlined here. This bug addresses a different section of the concepts guide, and the problem outlined here is different. Here, I am drawing attention to the fact that 2.2 should include only conceptual information about data entry. I am proposing changes to both sections, but the focus here is on streamlining 2.2. I'd like them to stay separate.
Yes, if this is a focus on chapter 4 and the concepts are explained in chapter 2, then I can agree with what you are saying. By keeping them separate then the two can be worked on separately also. Good point.
Hi David, > 2.2.2 should be truncated after the second paragraph, and the remaining content > there moved to 4.2. It might be useful to flesh out the discussion of double > entry bookkeeping here, but keep the actual register/splits discussion > elsewhere. Agreed, `2.2.2. Double Entry' is basically an amalgam of `2.1.3 Double Entry' and `4.2.2. Split Transaction'. In fact, the whole of §2.2 can be rearranged into: 2.2.1. Files (Books) 2.2.2. Accounts 2.2.3. Transactions with a general explanation of what each one is and pointers to later chapters for details. §2.1.3 can pick up the slack of explaining the double-entry concept. Which leads me to the question, how would you feel about editing DocBook XML? :-) Or editing the wiki page at [1] show suggested rewrite of the sections you're interested in? [1] http://wiki.gnucash.org/wiki/Concept_Guide#Ongoing_work
WRT docbook or Wiki: my skills are writing and editing technical documentation. I am ecstatic to finally be able to offer this project something back that actually means something. For now, I will continue to focus on the writing and editing, and hope you will indulge my method for offering it. That said--here's a stab: 2.2.1 Books Gnucash stores information at the highest level in books. An account book can be stored on your computer either as a single XML file (in all versions of Gnucash), or in a SQL database (in version 2.4 and higher). With the XML file format, GnuCash stores your data in an XML data file, usually in compressed format (although this can be changed in Preferences). With SQL storage, Gnucash stores your data in an SQL database under the database application you select. You will need one main file or database for each set of books you are maintaining. Note that if you think you might need more than one set of books, you might want to consult a professional accountant or bookkeeper before proceeding. Most users will probably have only one data file. Backup files and log files are automatically generated by Gnucash when appropriate. Backup and log files are described in Backing Up and Recovering Data. 2.2.2 Accounts An account keeps track of what you own, owe, spend or receive. Each set of books can contain many accounts. Examples of accounts include: checking accounts, savings accounts, credit card accounts, mortgages, and loans. Each account tracks the activity for that account, and can inform you of the status of that account. In addition, accounts are also used to categorize the money you receive or spend. For example, you can create expense accounts to track the money you pay on utilities or groceries. Even though these are not accounts that receive statements, they allow you to determine ow much money is being spent in each of these areas. These will be covered in more detail in Chapter 3. 2.2.3 Transactions A transaction represents the movement of money from one account to another account. Whenever you spend or receive money, or transfer money between accounts, that is a transaction. In double entry accounting, transactions always involve at least two accounts--a source account and a destination account. Examples of transactions are: paying a phone bill, transferring money from savings to checking, buying a pizza, withdrawing money, and depositing a paycheck. Chapter 4 goes more in depth on how to enter transactions in GnuCash.
Hmmm. Further reading of this suggests adding a sentence on splits in 2.2.3, right before the sentence beginning "Examples of transactions..." Something like: Each line within a transaction that tracks information for an account is called a split.
Created attachment 173860 [details] [review] Bug #633385 Hi David & Tom, Sorry this one took so long, I was really buried in work and chores this week. Brief summary of changes below. Please go ahead and review ruthlessly :-) Hoping to commit this by Sunday if all goes well. Restructure §2.2 Data Entry Concepts to only include basic info on files, accounts, and transactions. The old double-entry section can be effectively replaced by §2.1.3 Double Entry, and the section showing a detailed guide to entering a split transaction can be effectively replaced by §4.2.2 Split Transaction. Minor cosmetic edits to §2.1.3 and a concept clarification to §4.2.2.
I think that David has done a great job of improving the documentation by what I read in comment 5. GC has always had the notion that a transaction is moving money from one account to another as David expresses it in 2.2.3. I think that traditional phrasing is too restrictive because it focuses more on the mechanics rather than the essence of a transaction. This is not a quibble with David's rework. Rather it just pointing out now that I think down-the-line more work will need to be done on accurate expression of fundamental accounting concepts. Since I don't have the time to spend on it now, I will content myself with noting that I think later another cut should be taken at the definition of a transaction. I think this patch should be installed as presented. Once this and the related areas have been changed, I will have a better picture of how current planned changes will impact the guide. When I see the whole, I may see something that I am missing now by focusing on just this part.
Hi Tom, (In reply to comment #8) > [...] > > GC has always had the notion that a transaction is moving money from one > account to another as David expresses it in 2.2.3. I think that traditional > phrasing is too restrictive because it focuses more on the mechanics rather > than the essence of a transaction. I think you hit the nail on the head--to a certain extent, we are talking about abstract concepts which have been defined and used within the GnuCash program. It may be hard for a newcomer to see how GnuCash's notions of files, accounts and transactions can apply to his/her everyday finances. What could go a long way towards solving that is a set of well-done illustrations visually showing the movement of money between accounts using transactions and splits. I'm looking at options for such graphics now. In the meantime, I'm putting some finishing touches on the patch--fixing typos etc.--and getting ready to commit it into the main GnuCash repository.
Created attachment 173932 [details] [review] Bug #633385 Update patch to fix typo and minor transaction definition clarification.
Committed the patch at r19769. David, thanks a lot for the new and rewritten content! Tom, the rewrite looks a lot cleaner--what do you think?
Yawar and David, Responding to your question below: What I saw here [1] does seem much more straight forward and clear, a good improvement. [So the next remark is unrelated to this bug fix.] However, I am not sure I am looking at what was installed on 11/7. I do not see any reference to any release. I would find it most helpful to have a release specified as part of a page header. For example, this is the current page header in the browser version [1]: "GnuCash Tutorial and Concepts Guide". If it is possible to extract the release number into a variable that would be automatically updated, then if a person downloaded the docs for ease of reference on disk (when not online), the header could read: "GnuCash Tutorial and Concepts Guide [r19769]". If this is possible, then it should be incorporated into the PDF version of the docs also. What do you think? Tom [1] http://svn.gnucash.org/docs/guide/
Hi Tom, (In reply to comment #12) > [...] > What I saw here [1] does seem much more straight forward and clear, a good > improvement. [So the next remark is unrelated to this bug fix.] Sweet. > However, I am not sure I am looking at what was installed on 11/7. I do not > see any reference to any release. I would find it most helpful to have a > release specified as part of a page header. For example, this is the current > page header in the browser version [1]: "GnuCash Tutorial and Concepts Guide". > If it is possible to extract the release number into a variable that would be > automatically updated, then if a person downloaded the docs for ease of > reference on disk (when not online), the header could read: "GnuCash Tutorial > and Concepts Guide [r19769]". If this is possible, then it should be > incorporated into the PDF version of the docs also. > > What do you think? I think this is a great idea, but I wouldn't necessarily want to show the reader the revision number on every page--that makes it look too much like a draft. We could show it on the `About this Document' page which lists all the authors, copyright information and such. In terms of the XML sources, somewhere in the gnucash-guide.xml file. Could you file a bug for this? We can work out the details there. Cheers
Yawar-- There is a typo in the final text, which yields an editorial change: Under 2.2.2, "each account can contain many sub-accounts upto an arbitrary number of levels" Should be: "each account can contain many sub-accounts in an arbitrary number of levels" [saying "up to" implies a limit that is contradicted by the word "arbitrary"] Also, I think the dash in 2.2.3 should be entered as an mdash HTML entity. As for the assigning Gnucash version numbers for documentation, I would assume that SVN is meant for the development release, and that when the GC version is released, a set of documentation would be generated to go with that release. So embedding the release in the docs seems superfluous, although, like code, an embedded version number somewhere might make sense. Perhaps the documentation bugs should include a version?
GnuCash bug tracking has moved to a new Bugzilla host. This bug has been copied to https://bugs.gnucash.org/show_bug.cgi?id=633385. Please update any external references or bookmarks.