[GNC-dev] Wiki FAQ Page

David T. sunfish62 at yahoo.com
Tue Sep 4 17:53:56 EDT 2018


Frank,

I will begin with noting that I think that it was not entirely clear in my post that I was presenting only the top-level headings for the FAQ in this email; I was not prepared to re-align every level in the FAQ at this point. 

> On Sep 4, 2018, at 4:02 PM, Frank H. Ellenberger <frank.h.ellenberger at gmail.com> wrote:
> 
> Hi David,
> 
> at first thanks for starting with this task.
> 
> Am 04.09.2018 um 16:43 schrieb David T. via gnucash-devel:
>> Now, on a meta-level, I think the primary headings here might be better arranged as follows:
>> 
>> 1. General Questions
> Perhaps the title should be more specific. Abstract

The existing entry is "General Frequently Asked Questions (FAQ) about GnuCash". I was merely cleaning up the heading to make it more reasonable. I have no problems with a “General Questions” section. Perhaps others have suggestions here.

> About the project, how {this page is organized [missing]}, howw to get
> help (and provide required information, and give something back (from
> feedback to patches).

About the project belongs on the website or on the main page, not as an FAQ entry. 

How this page is organized *should* be clear from the main headings, which is what I am working on rationalizing. 

I duplicated the first FAQ entry "How to Get Help" at the very top of the FAQ, to bring greater prominence to this issue. I additionally left this as the first entry in the FAQ. Further, there is an entry on the topic on the main wiki page. Fourth, there is a “Getting Help" link on the main web page, which links to a separate "Getting Help” page on the wiki (https://wiki.gnucash.org/wiki/Getting_Help <https://wiki.gnucash.org/wiki/Getting_Help>). Honestly, how many more pointers to the help do we need?

Noting my comment above about only presenting at the top level in this first pass, I note that there are currently 4 second level sections in “General Questions,” (“General”, Contributing, Troubleshooting and Improvements, and Mailing List Questions) and that one or more of these sections might remain going forward. I will note that many of these issues are already incorporated into other pages on the wiki—or should be, IMHO—and that as I work through the sections, I am predisposed to relying on those pages, rather than a monolithic and overly-dense FAQ page to keep track of it all.

For example, the fourth top level section on the Main page of the wiki is entirely dedicated to giving back to the project. It would be my preference to see the pages and references on the main page serve as the primary source of information on these topics, and a single brief entry on the FAQ that points the questoner to those pages.

> 
>>  [move “Accounting Questions” to this section]
> Please do not, I see “Accounting Questions” more or less as "Off topic"
> there are spcefic websites which can answer such questions according the
> local law.

…except that a) general accounting questions are exceedingly common on the mailing lists, and b) these questions are already on the wiki. In the past, you have strongly advocated for including information on the wiki based on these two criteria; why change that now?

> 
> For me there is a logical sequence: Install, configure/customize, use.
>> 2. Installation
>> 3. Using GnuCash [moved ahead of cunfiguring]
> No, before you should configure/customize your installation.

This could go either way—but allow me to share my reasoning behind this arrangement. For *most* users, the first hurdle they will encounter after installation will NOT be configuring and customizing their brand new accounting software package; it’s going to be to run the program and try to figure out how to do basic things with said program. Questions about how to reconfigure GnuCash (which is what most of the entries under Configuring currently are) come *after* a user has been using the program for a while. Indeed, some users NEVER attempt to load a different font for their GnuCash.

That being said, there are a large number of these questions that by rights should be eliminated as duplicates of information in more official documentation locations. The entries for Filenames and Backups are prime examples. I don’t believe I would simply remove these questions from the FAQ, since they are so perennially-asked. However, I *am* again predisposed to streamlining these questions and moving the pertinent information to a separate page in the wiki.

> 
>> 4. Configuring and Managing
>>  [Move “Customizing" questions from current section 8 to this section]
> yes
> 
>> 5. Troubleshooting
> Please insert no separate Troubleshooting. It would lead to duplicate
> sections.

Currently, the heading is “Installation Troubleshooting” and contains installation questions and a whole lot of other crap that doesn’t belong under Installation. *That* is an excellent recipe for duplication of information, as evidenced by the current state of information on the wiki, IMHO. Having a separate Troubleshooting section would, I believe, actually serve the end user better than what we have right now.

> 
>> 6. Exporting and Importing Data
>> 7. Business Features
> In theory 6 & 7 are subsections of 3
> 
>>  [Move entire Developing GnuCash section of questions to the pages established for Developers]
> No, there should be only one FAQ. Because it might not interest most
> users , it is at the bottom.
> I am pretty sure, if we would break the FAQ in parts we would end with a
> bunch of duplicated sections.

There are 7 entries in this section. I will enumerate them here and give further info under each.

1) I heard it is too hard to compile GnuCash!

Setting aside that this is not even a question, the answer here references GnuCash 1.6.0 (!!!!). It seems to me that https://wiki.gnucash.org/wiki/Building <https://wiki.gnucash.org/wiki/Building> might have a little more up-to date information on this subject.

2) Ok, what devel packages do I need in order to compile GnuCash?

Again, this is covered on other pages of the wiki. Indeed, the answer refers the user to the dependencies page.

3) Why is GnuCash written in C?

4) Why don't you rewrite GnuCash in programming language ''xyz'' so that I can contribute easily?

5) Can I read the doxygen files documenting the API offline?

and

6) Can I run GnuCash already in the build dir?

These questions do come up—on gnucash-devel. I feel that this information belongs more appropriately on the pages for development, rather than here.

Finally,

7) How do I run GnuCash under gdb and get a stack trace?

This references the external Stack Trace wiki page, but I would move it to the General Questions FAQ section, under Troubleshooting. I will note here that there is also a “Tracefile” page on the wiki; I haven’t compared the two entries, but would not be surprised to see extensive duplication of information, with one being woefully out of date.

> 
>> I welcome input and feedback.
> 
> As you have already started, I would prefer - like for patches - smaller
> changesets (move section x into...). Diff is not very smart and it is
> now almost impossible to see what really changed.
> 

I have worked on the FAQ in a series of unitary changes thus far. Each of my commits states it purpose. I admit that the edit of the Importing section at 16:34 today states somewhat generically that it is making major changes to the section. Most of the changes in this edit were one of two types: 1) removing nonfunctional (e.g., links to user websites that are now offline) or outdated information; and 2) moving the questions around so that they followed a logical progression (Importing before Exporting; Quicken before QuickBooks before MSMoney before specific providers before generic CSV importing).

To be honest, Frank, this feels like another instance of your not trusting that I am able to make informed editorial changes to the wiki. Have you looked at the 7 edits on the FAQ I made today? Or the 9 I made last week? How are these changes “impossible to see?"


> Why did you remove the table to the official docs? Many questions are
> already answered there.
> 

See my comments above about the numerous ways in which the user is directed to the documentation that is available to them. I personally think that 5 different routes is enough.


>> David
> 
> Frank
> 



More information about the gnucash-devel mailing list