GNOME Bugzilla – Bug 687820
Proposal to restructure Tutorial and Concepts Guide
Last modified: 2018-06-29 23:11:39 UTC
Per discussion in Gnucash-devel, I propose that the chapter structure of the Tutorial and Concepts guide be adjusted. The new chapter structure would use the main account structure described in "2.1.1. The 5 Basic Accounts" to arrange the following chapters. Additional modifications are necessary to enable this structure to be clear. Specifically: Realignments: * Chapters 3 and 4 would become sections of Chapter 2. * Chapters 5, 8 & 16 would become sections of Chapter 3. * Chapters 6 & 7 would become sections of Chapter 4. * Chapter 9 would become a section of Chapter 6. * Chapter 10 would become Chapter 8. * Chapter 15 would become Chapter 9. * Chapters 12, 13, & 14 would become sections of Chapter 10. * Chapter 17 would become a section of Chapter 11. Major textual adjustments: * New text would be necessary for chapter 5. * Chapter 4 may need a new section for Other Liabilities. * Text in Bug 687290 would become the basis of New Chapter 7. * New introductory text would be necessary for New Chapters 3-7. * New text on Custom reports would (IMHO) be advised for chapter 11. Issues for further consideration: * Placement of Chapter 11 (Depreciation) is not clear. Would it be better under Business Features, or some other section altogether? The proposed new chapter structure, therefore, would be: 1. Overview 2. The Basics 2.1 Accounts 2.2 Transactions 3. Asset Accounts 3.1 Checking Accounts 3.2 Investments 3.3 Other Assets 4. Liability Accounts 4.1 Credit Cards 4.2 Loans 4.3 Other Liabilities 5. Equity Accounts [new text necessary] 6. Income Accounts 6.1 [new text necessary] 6.2 Capital Gains 6.3 Other Income Accounts 7. Expense Accounts [new text necessary, based on bug 687290] 8. Multiple Currencies 9. Budgets 10. Business Features 10.1 A/R 10.2 A/P 10.3 Payroll 11. Extending Gnucash 11.1 Custom Reports 11.2 Python Extensions
Could this be implemented as a change in the Tutorial and Concepts guide for release 2.5.x where x is greater than 1?
No one else has brought this up or commented since I posted it, so I imagine that these changes would be (at best) rendered somewhere down the line (that is, not in the immediate development cycle). The main docs person has not been that active recently, and I do not have the skills to push the changes along by myself. Someone with skills and time would have to work the documentation to get it into the newer format.
+1 from me, but: * before we should solve Bug 722016 * the business section should first have a setup section, which currently is partially and redundatly hidden in the existing chapters or needs to be written (Sales Tax Table editor, Billing Terms Editor) [see Bug 705309] and a chapter about vouchers before payroll. * I am currently missing ** online banking ** fetch quotes online by Finance::Quote Are they somewhere hidden or unwritten? @sunfish: your good ideas are hard to read if you only write "chapter x". If you could write e.g. "1. Overview", "Chapter 1 - Overview" or "Chapter 1 (Overview)" it would be much easier as not all published formats are showing the chapter numbers and numbers might change. This affects also your other bugs.
Frank-- Thanks for the vote. I don't understand why the document development platform should hinder content development. As I am a personal accounts user, I have almost no contact with the business features. As far as I understand (based on what I read in the lists), these areas are not documented much (if at all). I think adding coverage for such aspects is important, especially given the amount of times users ask questions about them. I however, am not the person to provide that. However, given the immense complexity of the business features, I wonder whether it would be better to have an entirely separate document (that is, neither the current Help or Tutorial docs). I believe there is enough complexity that it would be warranted--and many personal users have no need to even know about them. If a separate Business Features document seems unrealistic, then just make a suggestion about what you'd want to have and where you'd place them. Online features should definitely turn up somewhere here; offhand, I don't know whether they are embedded anywhere. But embedded isn't probably good anyway. Perhaps it would be helpful to insert one or more chapters in the sequence just after the Expense Accounts chapter (chapter 7 in my new sequence). These chapters could cover the online banking and F::Q topics, among others. A chapter on using reports might be helpful as well. I'll note that online banking practices vary substantially by jurisdiction; those of us in the US do not use a lot of it, and any text on it would have to take that into account. I think your final comment refers to my initial realignment text; I thought the new chapter structure (and the existing contents) would make clear what was going to end up where. Sorry to cause difficulty.
I also don't think we should be waiting for a new document development platform to continue to improve the current documentation. Once we have such a platform in place it will be a one time switch of the documentation as is at that point to the new platform. There is currently a discussion going on again on the devel list on what such a new platform should look like. As for the new structure. That looks good although it may need some tweaks depending on the outcome of the current debate on the devel list over merging the documents into one. Lastly don't worry about the business features if you don't use them. Just keep them in the structure (with whatever information is currently already in the documentation). Someone else can come in and fill in the details at any time.
Update 2017: The Guide has seen many changes to its structure, but I still believe that most of these changes still are pertinent. Here is a listing of current chapters and their destinations now: Current Future 1. Overview 1. Overview 2. The Basics 2. The Basics 3. Accounts 2.1 Accounts 4. Transactions 2.2 Transactions 3. Asset Accounts 5. Checkbook 3.1 Checking Accounts 9 Investments 3.2 Investments 3.3 Other Assets 4. Liability Accounts 7. Credit Cards 4.1 Credit Cards 8. Loans 4.2 Loans 4.3 Other Liabilities 5. Equity Accounts [new text necessary] 6. Income Accounts 6.1 [new text necessary] 6.2 Capital Gains 6.3 Other Income Accounts 6. Expense Accounts 7. Expense Accounts 8. Multiple Currencies 8. Multiple Currencies 18. Budgets 9. Budgets 13. Business Introduction 10. Business Features 14. Business Setup 15. Accounts Receivable 10.1 A/R 16. Accounts Payable 10.2 A/P 17. Payroll 10.3 Payroll 19. Other Assets 11. Other Business Assets 20. Depreciation [retain?] 22. Importing Business Data 12. Importing Business Data 13. Extending Gnucash 13.1 Custom Reports 21. Python Bindings 13.2 Python Extensions Glossary A. Migration Guide B. Frequently Asked Questions C. Contributed Account Trees D. Auxiliary File Formats NOTE: The Appendices in the Guide appear to contain information that is quite dated (>5yrs as of early 2017). I will propose action on these in a different set of bugs.
In general yes, but ... Update of dependencies: - 722016 That is an independend question and no solution in view. + 777318 David told on the mailing list. Technical aspect: Until now we have a main document without real text. Should the intros of the chapters become part of the main document or the &chXX; move down in the main chapters? [Pro/Con] From my POV Deprecation is a subchapter of Expense Account as Capital Gains are from Income Accounts. Example subprime crises: the value of your real estate has dropped. How should you track it? Its value should usually be higher than the respective mortgages.
Chapter Expense Accounts was initially after Checkbook and for me that seemed a good spot. It's an easy concept to grasp and something you'd want probably need quite soon when you start with gnucash. I understand you want to group accounts by type. How about starting with Asset accounts, followed by Income accounts, then Expense Accounts, and then continue as you propose ? That puts the easier to grasp types more on top.
Frank, Thanks for updating the dependencies, although if my plan of action goes forward, this bug will essentially be a roadmap for a host of subsidiary bugs that enact the real changes. I don't understand what you are getting at in the Technical aspect paragraph. When you say "main document" do you refer to "gnucash-guide.xml"? Personally, I don't really see the point in that; could you explain what any such change would accomplish, from either the end user or doc-writer's perspective? As I mentioned on the devel list, I believe that there was a suggestion to get rid of the chapter on Depreciation altogether, for a number of reasons. It definitely doesn't belong with Expense accounts. Your example might link with capital gains ("Capital gains" in this case includes "Capital losses"). But I believe the concern with depreciation is that it is highly dependent on jurisdiction, and so our advice is bound to be wrong for many. Geert, I moved the sections around in an attempt have the classes of accounts appear in the same order as they appear in a general ledger, which is Assets, Liabilities, Equity, Income, and Expenses. If you prefer a newbie-friendly sequence (regardless of the GL), I might suggest: Assets, Expenses, Income, Liabilities, and Equity. What do you think?
(In reply to Geert Janssens from comment #8) > Chapter Expense Accounts was initially after Checkbook and for me that > seemed a good spot. It's an easy concept to grasp and something you'd want > probably need quite soon when you start with gnucash. I understand you want > to group accounts by type. How about starting with Asset accounts, followed > by Income accounts, then Expense Accounts, and then continue as you propose > ? That puts the easier to grasp types more on top. Did you see my comment 9? Should I proceed with a) the formal ledger sequence (Assets, Liabilities, Equity, Income, Expenses), b) your proposed sequence (Assets, Income, Expenses, Liabilities, Equity), or c) my modified last sequence (Assets, Expenses, Income, Liabilities, Equity)
David, I'd go with your last modified sequence. A concepts and tutorial guide doesn't need to follow structure in the account hierarchy. It should be structured so the user can build upon previous knowledge so the easier topics should come first (in my humble opinion).
For me there is a logical sequence: Q: Why should you do accounting? A: To answer a few of your questions: Q1: How poor or rich am I? A: See the balance sheet: Assets - Liabilities = Equity Q2: How successfull am I? A: See the P&L report: Income - Expense [Q3: Will I can pay my invoices? A: Group your assets and liabilities by maturity. Starting with short terms your assets should always be greater than your liabilities ...]
I would expect a discussion on Depreciation to be included with Assets, not expenses. (though it's termed 'Depreciation Expense' as a tax implication) Most texts I find present it as a contra-asset account and it's presented on a Balance Sheet there as reducing the value of an asset. (though on a P&L it's listed at the bottom as an expense) Thus I'd propose: 3.4 Contra-Assets 3.4.1 Depreciation In line with that, perhaps each chapter could include a contra-accounts section for those relevant (albeit little used) accounts. If there is to be a separate Business oriented guide, then certainly, the contra-sections should be included there and not in the Personal guide. As well, in a Personal guide I think there is need for an explanation on handling cash-basis accounting and reporting since that workflow is going to be much more prevalent for personal use cases. I'm not sure if that should be the primary perspective of the Guide as a whole, or a separate chapter, or special notes in each section.
GnuCash bug tracking has moved to a new Bugzilla host. The new URL for this bug is https://bugs.gnucash.org/show_bug.cgi?id=687820. Please continue processing the bug there and please update any external references or bookmarks.