After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 708267 - Budget documentation is out of date
Budget documentation is out of date
Status: RESOLVED FIXED
Product: GnuCash
Classification: Other
Component: Documentation
2.4.x
Other All
: Normal enhancement
: ---
Assigned To: gnucash-documentation-maint
gnucash-documentation-maint
Depends on:
Blocks:
 
 
Reported: 2013-09-17 21:45 UTC by R Ratliff
Modified: 2018-06-29 23:19 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Add budget documentation (11.91 KB, patch)
2013-09-17 21:47 UTC, R Ratliff
none Details | Review
Add budget documentation (minor revisions) (11.96 KB, patch)
2013-09-18 13:39 UTC, R Ratliff
none Details | Review
Add budget documentation (15.06 KB, patch)
2013-09-19 04:02 UTC, R Ratliff
none Details | Review
Update budget documentation (16.76 KB, patch)
2013-09-24 00:44 UTC, R Ratliff
none Details | Review
Add budget documentation (17.38 KB, patch)
2013-10-23 20:03 UTC, R Ratliff
committed Details | Review

Description R Ratliff 2013-09-17 21:45:57 UTC
The following pieces are undocumented:

* The budget toolbar buttons (e.g. What does Estimate do?)
* The budget reports
* The budget Actions (New, Open, Copy)

I'd like to see a basic coverage of the features and a more in depth guide on how to use the budget functionality to actually _do_ budgeting.
Comment 1 R Ratliff 2013-09-17 21:47:39 UTC
Created attachment 255140 [details] [review]
Add budget documentation

This patch adds the most basic coverage of the budget functionality. I've left some parts blank (the documentation of the budget reports), and I think more sections could be written.
Comment 2 R Ratliff 2013-09-18 13:39:21 UTC
Created attachment 255218 [details] [review]
Add budget documentation (minor revisions)

The only differences between this and the previous patch is I added myself as an Author to the commit message and I removed some trailing whitespace from the end of lines (Git highlights this as red).
Comment 3 R Ratliff 2013-09-19 04:02:03 UTC
Created attachment 255268 [details] [review]
Add budget documentation

Additional documentation. More information about budget reports, added a procedure for adding a budget value.
Comment 4 R Ratliff 2013-09-24 00:44:26 UTC
Created attachment 255599 [details] [review]
Update budget documentation

I added three paragraphs to chapter 15 of the guide on budgets. These paragraphs describe two reports used in budgets, the budgeted income statement, and the budgeted balance sheet.

I've put this in the guide instead of the help, because in order to put it in the help I would like to be sure that this is really the way those two reports work in GnuCash.
Comment 5 Wm 2013-10-04 15:25:56 UTC
Guide: I prefer the wording of the last sentence of 15.3.2 to 15.3.1, i.e. it should be really clear to the new comer that the budget versions of these reports are nothing to do with historical / real data, there is no comparison as there are in other budget reports, etc.  Specifically I think the words " includes the predictions made in the budget" could be read as the BIS including historical / real data.

Do you think it is worth expanding this section of the Guide to include the Budget Barchart (useful to home users too) ?  I'll write it up.

I don't think the other Budget reports are of enormous use as they are.  Have you looked at them all?  What do you think?
Comment 6 Wm 2013-10-04 15:36:41 UTC
Help_ch_Customize.xml: I couldn't get the patch to work here (the others were fine).  Probably a problem at my end as I am hacking this on Win XP + cygwin.  I didn't bother investigating it much as it seemed the least significant of your changes, having said that I think the problem might be this bit


       < / sect2 >
 
       < sect2 id="business-book-options" >

i.e. it looks like sect2 ends before it begins.
Comment 7 Wm 2013-10-04 16:26:20 UTC
Help_ch_GUIMenus.xml

4.7  

s/This window is shown when Actions → Budget → Open Budget is selected from the Menubar. This will open a new tab with the budget displayed./Actions → Budget → Open Budget will open the default budget or offer you a choice if there is more than one budget. A new tab will open with the budget displayed./

4.7.13  do you think "book options" is better than "File -> Properties -> Budgeting" or does everyone know where "book options" is ?  Also I think there are some circumstances where it doesn't behave this way but I've never investigated enough to pin it down.

Table 4.32

The Budget Flow report is broken, for example if you choose month 1 of 12 it shows month 2 and won't allow you to choose month 0; if you choose period 2 it shows period 3, etc.

Fill in Budget Bal Sheet and Budget Inc Stmt, you have these right from your Guide descriptions.

For Budget Barchart say "Gives a graphical representation of Budget vs Actual figures for an account or accounts"

Am I right in thinking you became stuck on the detail of
 Budget -> Options
and 
 Budget -> Estimate
don't worry, *everyone* is :)  That is the next step.

You've done a good job, tidy up as you feel fit and let us know when to have another look.  You may e-mail me if you want but I prefer to keep things on the list (not here).  I won't look here ordinarily.
Comment 8 R Ratliff 2013-10-23 20:02:24 UTC
(In reply to comment #5)
> Guide: I prefer the wording of the last sentence of 15.3.2 to 15.3.1, i.e. it
> should be really clear to the new comer that the budget versions of these
> reports are nothing to do with historical / real data, there is no comparison
> as there are in other budget reports, etc.  Specifically I think the words "
> includes the predictions made in the budget" could be read as the BIS including
> historical / real data.

I changed the words "includes" to "is based on." To be honest, I'm not exactly clear on whether the Budget Income Statement includes historical data or not. All I know is that it is a prediction, which the documentation clearly states.

> 
> Do you think it is worth expanding this section of the Guide to include the
> Budget Barchart (useful to home users too) ?  I'll write it up.
> 
> I don't think the other Budget reports are of enormous use as they are.  Have
> you looked at them all?  What do you think?

My view is that the documentation is a bit of a wiki. If it is incomplete now, someone can always add to it later. I don't think any of the other reports are worth writing about for now.

(In reply to comment #6)
> Help_ch_Customize.xml: 
> [snip]
> I think the problem might be this bit
> 
> 
>        < / sect2 >
> 
>        < sect2 id="business-book-options" >
> 
> i.e. it looks like sect2 ends before it begins.

Wm, thanks for your comments. I'm beginning to sift through this. Those two lines </sect2> <sect2... are a part of the patch context, so they shouldn't throw anything off. 

(In reply to comment #7)
> Help_ch_GUIMenus.xml
> 
> 4.7  
> 
> s/This window is shown when Actions → Budget → Open Budget is selected from the
> Menubar. This will open a new tab with the budget displayed./Actions → Budget →
> Open Budget will open the default budget or offer you a choice if there is more
> than one budget. A new tab will open with the budget displayed./

Wording has been changed.


> 
> 4.7.13  do you think "book options" is better than "File -> Properties ->
> Budgeting" or does everyone know where "book options" is ? 

I've linked to section 9.3 of the documentation that explains what "Book Options" is.

> 
> Table 4.32
> 
> The Budget Flow report is broken, for example if you choose month 1 of 12 it
> shows month 2 and won't allow you to choose month 0; if you choose period 2 it
> shows period 3, etc.

On my version (unstable) it seems to work. But if that report is broken, it should really be a separate bug.

> 
> Fill in Budget Bal Sheet and Budget Inc Stmt, you have these right from your
> Guide descriptions.
> 

My descriptions in the guide are what those reports should do. However, I have  no idea if the GnuCash reports match up to that. They are definitely some of the more complex reports I've seen.

> For Budget Barchart say "Gives a graphical representation of Budget vs Actual
> figures for an account or accounts"

This report doesn't work on the version I'm writing this on, so I'll have to document it later in another patch, and maybe report a separate bug.
Comment 9 R Ratliff 2013-10-23 20:03:28 UTC
Created attachment 257964 [details] [review]
Add budget documentation

    commit e30930c0fc4118180ac981085b2708eaf355b872
    Author: Bobby Ratliff <ratliff.bobby@gmail.com>
    Date:   Wed Oct 23 14:56:42 2013 -0500
    
        Minor budget documentation fixes
    
        * Changed wording in guide 15.3.1 (budget income statement)
        * Changed wording in help 4.7 (Budget window)
        * Added link to "book options" in case users don't know what that is
    
    commit a4f9b78dfb10e8a3375a6b35ca510eae14df9b1b
    Author: Bobby Ratliff <ratliff.bobby@gmail.com>
    Date:   Tue Sep 17 15:14:00 2013 -0500
    
        Add budget documentation
    
        GnuCash help:
        * 9.3.2: Clarify that the 'default budget' option is for budget reports
        * Add a section about budgets to Chapter 4.
    
        GnuCash guide:
        * 15.3: Describe budgeted income statement and budgeted balance sheet
          reports from a conceptual perspective. Note: This doesn't necessarily
          document the way these reports work in GnuCash.
    
        Author: Robert Ratliff <ratliff.bobby@gmail.com>
Comment 10 Geert Janssens 2013-10-26 10:12:40 UTC
Comment on attachment 257964 [details] [review]
Add budget documentation

From Wm Tarr's comments there were no big issues in your original patch and your reworked patch improves it even further. In addition the patch applies cleanly and gives no xsltproc errors, so I saw no reason to keep it waiting anymore. Committed as r23339. Thank you very much for this much needed update of the documentation.
Comment 11 Geert Janssens 2013-10-26 10:12:57 UTC
This problem has been fixed in the development version. The fix will be available in the next major software release. Thank you for your bug report.
Comment 12 John Ralls 2017-09-24 22:45:38 UTC
Reassign version to 2.4.x so that individual 2.4 versions can be retired.
Comment 13 John Ralls 2018-06-29 23:19:21 UTC
GnuCash bug tracking has moved to a new Bugzilla host. This bug has been copied to https://bugs.gnucash.org/show_bug.cgi?id=708267. Please update any external references or bookmarks.