GNOME Bugzilla – Bug 633590
Document the GnuCash reports
Last modified: 2018-06-29 22:46:27 UTC
The only mention of reporting in the concepts guide is in subordinate sections of the concepts guide (4.7.5, 5.5.5--others?). Reporting is fundamental to daily use of Gnucash and this document needs to offer users a clear place to find that help. Some of this information might appropriately be placed in the Help manual; I am not up to figuring that out right now... 9. Reports Gnucash is a powerful double entry accounting software package that allows users to enter and track their money in a reliable manner. However, putting this information into Gnucash is only a part of the process. To be truly helpful, you need to be able to extract this information in meaningful ways. Gnucash's reporting features allow you to just that. Gnucash's reporting features allow you to display nearly any group of transactions in a wide variety of formats. This makes it easy to answer questions about your finances, such as "How much did I spend on groceries last month?" or "How much did I earn in the previous six months?" Gnucash includes a number of common report types, which can be modified to meet your specific needs. If these common reports are insufficient, it is possible to modify or even write your own custom reports (although this is not recommended for beginners). 9.1 Basic Concepts Gnucash's reports are available on the Reports menu. When you select a report from the list of reports, that report is first run with its default settings. Once you have opened the report, you can modify its parameters by clicking on the Options button on the toolbar. Under Options, you will see the different settings that you can change for each report. Note that for different reports, the options will be different. 9.2 Specific Reports 9.2.1 ... [perhaps move sections found elsewhere, such as 4.7.5 and 5.5.5, here]
Hi David, you're right that some of this info already exists in the Help Manual. Specifically, see [1]. I believe a good rule of thumb to separate Manual content from Guide content is: if it is an input to GnuCash, an output of GnuCash, or can be accessed through the GnuCash user interface, it should be fully explained in the Manual and partly covered in the Guide; if there is a conceptual model behind what's going on that the user needs to know about to understand or work with GnuCash, it needs to be in the Guide. You're right if you just thought that there's some overlap there. I think that is necessary to some extent; the two documents (especially the Guide) do need to be self-contained enough that they don't interrupt a reader's progress every few minutes to look something up elsewhere. Also, I agree with you completely that reporting needs to be a `star attraction' of the Guide, especially given how many posts we see to the mailing lists about reports. So that said, I'm confirming this bug and turning your comment into a patch. Thanks! [1] http://svn.gnucash.org/docs/help/Reports.html
*** Bug 575895 has been marked as a duplicate of this bug. ***
Something I just noticed is that we have a reports chapter (created by Jon Lapham in 2003) in the guide, it's just in skeletal format, and not included in the main DocBook XML file! So that is a good starting point for report documenters. The file is guide/C/ch_reports.xml
I would propose using my section 9.0 to replace "Report Concepts", and using my 9.1 to replace "Overview" in this stub file as a beginning. These headings can be used in favor of mine. My text makes an initial attempt to clear up a number of aspects of reporting that raise questions on the lists. Then, we can create basic descriptions of the reports that are there. I am not sure that the table in the original is particularly helpful. I culled the following descriptions from a quick search of the user list; these are how I might imagine the report-by-report description going. I do not know whether this information belongs here or in the Help guide, but it needs to go somewhere. The text here focuses on what the reports mean, rather than where they are in the menu, which is why I vote for putting it here. If you think it better for the Help guide, then let's put it there. Balance Sheet Report A Balance sheet report lists Asset, Liability, and Equity account balances for all such accounts, and provides totals on a given date. Balance sheets are commonly run for the last day of each fiscal year to give an overall sense of the financial condition of the entity. Income Statement Report An Income statement report is also called a "Profit and Loss" report. This report lists Income and Expense account totals for a set period. The Income statement helps show where your money is coming from, and where it is going to for a given time period.
I more or less stand behind what I said before regarding where documentation on reports needs to be spread out throughout the Help and the Guide, but have come to think that reporting needs to be integrated into the Guide as much as possible. I.e., the rest of the material in the Guide needs to reference using reports to accomplish their tasks wherever possible. And reporting does need to be given some focus in the Guide--so I'm pinning the Reports chapter right after the Transactions chapter. I'm trying to say that reporting is fundamental. As for the Help--I mean to move all the descriptions of the reports and their options into the Reports chapter in the Help. They should be in the form of a `in a nutshell'-type reference for each report. This is a big task, and I want to split it up over several patches. But at the same time I really don't want to maintain two different patch series in Bugzilla. So I'm going to try something new--while the work is in progress, which may be weeks to months, I'm going to push everything to my personal gnucash-docs clone on GitHub (https://github.com/yawaramin/gnucash-docs), specifically to the following two branches: * bug-633590-trunk * bug-633590-2.4 (right at the end) Let's see where this goes.
I agree with your projected goal. It seems to me that the logical starting point, then, is to fill in the individual descriptions themselves. Everything else hinges off that. Therefore, filling in these blanks would be step one. This is a big task, I agree. Looking at the help pages in question, I wonder if there is a way to modularize it further, so that each report can be described individually, and then rolled into the final output? It would be much cleaner to be able to fill in a consistent set of data points on each report. Such an approach would help ensure that users would be given the same information on each report. Descriptive elements might include: Title, Description/Purpose, Settings. An atomized approach will also make it easier to divide and conquer the list. I can help with this--if the two descriptions I provided in comment 4 match what you mean by "in a nutshell." I'll note that some reports will be easier to describe than others. The Account Summary report is easy; the Budget Report, maybe not so much; and how do you describe the Advanced Portfolio and its idiosyncrasies? One area I think needs to be watched closely is that of the broader reporting issues. For example, where do things like the explanation about changing options after first running the report go? In the Help guide, or the Tutorial? Where do we inform the user about using reports to glean information for a particular time period?
David, (In reply to comment #6) > I agree with your projected goal. > > It seems to me that the logical starting point, then, is to fill in the > individual descriptions themselves. Everything else hinges off that. Therefore, > filling in these blanks would be step one. Exactly. > This is a big task, I agree. > > Looking at the help pages in question, I wonder if there is a way to modularize > it further, so that each report can be described individually, and then rolled > into the final output? It would be much cleaner to be able to fill in a > consistent set of data points on each report. Such an approach would help > ensure that users would be given the same information on each report. > Descriptive elements might include: Title, Description/Purpose, Settings. An > atomized approach will also make it easier to divide and conquer the list. If you look at the Help > Reports and Charts > Assets & Liabilities section, for example, the docs authors started doing that. The skeleton of this layout is there. I just mean to put each report in its own subsection so that it can have a nice heading and we can immediately jump to that exact subsection from other parts of the docs or from the GnuCash UI itself if need be. And give each report those descriptive elements you mention. > I can help with this--if the two descriptions I provided in comment 4 match > what you mean by "in a nutshell." Combined with my above paragraphs, yes--a very brief description of the report, followed by its particular options and properties. You can just post text files with report descriptions and specifications following this format. Or you could create a wiki page in the GnuCash wiki dedicated to reports and fill it in. Then I could go in, pull off whatever I found there, and delete it from the wiki page to let you know I'd processed it. I'd appreciate any help--there's a lot to do here :-) > I'll note that some reports will be easier to describe than others. The Account > Summary report is easy; the Budget Report, maybe not so much; and how do you > describe the Advanced Portfolio and its idiosyncrasies? Yeah, some reports will be particularly complex to describe their properties and behaviours. We can ask for help with those. > One area I think needs to be watched closely is that of the broader reporting > issues. For example, where do things like the explanation about changing > options after first running the report go? In the Help guide, or the Tutorial? I've actually added exactly this information in my first commit on this project--see https://github.com/yawaramin/gnucash-docs/commit/2ff775ab7d4c3bac332e7beae0528464d025c2bf You can actually follow the progress on this bug by going to the page for the branch I created on GitHub: https://github.com/yawaramin/gnucash-docs/commits/bug-633590-trunk (RSS feed available too). > Where do we inform the user about using reports to glean information for a > particular time period? I touched on that very briefly in my second commit: https://github.com/yawaramin/gnucash-docs/commit/0da77d4261df3572638c904e32b66f042be0a8bd#L0R76 P.S. I'd be happy to help if you need tips on navigating GitHub. Email me if needed.
Quick question-- Is there a way to generate a list of options and settings for all the reports from the code base? It would be a whole lot nicer to not have to type that up...
I have begun putting brief descriptions into: http://wiki.gnucash.org/wiki/Using_GnuCash#Reports_Included_in_GnuCash Because the wiki page enumerates all the reports in Gnucash, I think it would be best if you copy the descriptions and leave them there; I can work to fill in the blanks--but only if the blanks remain a diminishing set!
@David: Your recent message on the list brought this bug to my attention. In direct response to comment 9: I'm fine with keeping the report enumeration in the wiki for now. However in the long run I'd rather have that info solely in the manual. The main reason for that is to avoid duplicate effort of keeping both in sync (when reports get added/changed/removed). Other than that I'm fine with the general proposals in the enhancement request. Your comment 6 makes a lot of sense (more modularization of the reports). I wanted to pull the work Yawar started from his personal git repository, but unfortunately it's gone so we'll have to start from scratch. Feel free to convert the information you provided so far into a patch which I'll gladly apply.
Created attachment 310210 [details] Overview of options per report In reply to comment 8 - is this attachment close to what you had in mind ? There is unfortunately no easy way to enumerate all report options in code. Instead I temporarily hacked the main report code to print this info while loading gnucash. The "General Ledger" and "General Journal" reports reported (no pun intended) errors with this extraction method. I'm pretty sure they both have more than 2 options so you still have to look those two up by opening the options dialog yourself. Lastly: some reports will list options or sections that start with underscores. Those should not be documented. They are only used internally by gnucash. The user will never be able to configure those.
Created attachment 310211 [details] Quick and dirty hack used to dump the report options Just for future reference I will attach as well the hacky code changes I did to make gnucash dump the report options. THIS IS NOT A DECENT PATCH MEANT TO BE COMMITTED TO THE PUBLIC REPOSITORY ! It can be temporarily applied do get the dump and then remove the patch again. Note to use it, one should change the path for the dumpfile (it currently points to my homedirectory which is unlikely to be available for others).
Geert, Thanks for the listing of options. I think it will serve as a useful tool going forward. Whether it gets used in the actual reports chapter, or gets added as an appendix is another issue. But it will certainly help inform the report description process. My current view is that the descriptions will give an overview of the reports (what data they use, what purpose they serve), and then refer to a master list of settings. Perhaps this settings info would go into the Help document, while the descriptions would go into the Guide.
Every time I try to get a report of anything ijust get a blank page Can anybody help
(In reply to philip from comment #14) > Every time I try to get a report of anything ijust get a blank page > Can anybody help 1. Don't hijack bugs. 2. Don't use the bug tracker for support requests. Subscribe to gnucash-users@gnucash.org and ask for help there.
I will vote for attachment 310210 [details] to be formalized and made a selectable option to be added as an additional page for any report.
New chapter added to Guide 2016-10-21 via Github.
GnuCash bug tracking has moved to a new Bugzilla host. This bug has been copied to https://bugs.gnucash.org/show_bug.cgi?id=633590. Please update any external references or bookmarks.