Guide Documentation

[David T.]

Pedro, 

Again I thank you for working on the documentation. It always can use the extra help!

> On Feb 26, 2016, at 4:56 PM, Pedro Albuquerque <palbuquerque73 at gmail.com> wrote:
> 
> Hi
> 
> since reports documentation is not really available, here is an idea.
> 

I agree that the reports documentation is sparse. There are a number of issues to address:

First: coordinate the information that is in the Help and in the Guide. Currently, there is the stub information in Help, while the Guide has some reporting information sprinkled sparsely among the various chapters. There is a bug report requesting a separate reports chapter in the Guide.

Next: the nature of what each of these main documents should include should be considered and clarified. I think it might be sufficient for the Help document chiefly to identify how to use the reports in general (e.g., noting that a report’s options are modified only after the report is initially invoked) and then list the various reports. Then, the Guide could be used to describe the individual reports in more detail, with a description for each on how it is intended to be used. This latter would use the descriptions that are slowing growing in the wiki.

> I think it can be consensual that reports should have a dedicated
> section, since they affect both business and personal finances, and are
> the only way to keep our accountants happy  ;-) .
> 
> So, I used the existing ch_reports.xml as base and:
> 
> 1 - Divided it, because it seemed to me that a single file for all
> reports documentation would be to big. There isn't any logical reason
> for this split.

I don’t really agree with splitting the xml files at this level for a couple of reasons: 

First, many reports are used by different user groups. A personal user might not think to look in the business section for the Balance Sheet, but it certainly is useful to them.

Second, while long xml documents can be daunting to edit in a text editor, there are many ways around this, and for many users who access the help through a browser are going to get section-based pages anyway.

I would prefer ch_reports.xml to remain a single document.

> 2 - The split is based on the Reports Menu it self. Apart the general
> concepts, there is a file for each sub-menu and one for the general
> menu.
> 3 - Another file/section could be created for the How-to's, or they
> could be integrated in the Example section.
> 4 - I used the existing tables and expanded them to the list of
> available reports. 
> 5 - I did not create anything, except some links between tables and
> files, and the screenshots, and even those would have to be EXIF cleaned
> and size adjusted.
> 6 - Nothing is finished nor complete. I used Accounts Summary Report as
> the only example to illustrate my idea.
> 
> 7 - I didn't use git patch because I wouldn't know how. Please forgive
> my ignorance, but this way is easier for me, and probably for you
> developers.
> I think I've made my fair share of git mistakes for you to endure with.
> 
> As said before, I'm available to help, but never to create unnecessary
> discussions. It's just an idea, please do completely disregard it if it
> is not in line with the roadmap or any other existing guidelines. Since
> it was accepted within my translation (to be changed, if needed), here
> is the English version with one single not pt translated example.
> 
> Regards,
> Pedro.
> 
> P.S.: my github fork is updated, I think, so the files should be also
> available there.
> <face-wink.png><C.zip>_______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel