[GNC-dev] Documentation--What else?

[David T.]

Hello,

I am going to raise—once again—the spectre of the conflicting and duplicative information in the various documentation packages in relation to online quote retrieval.

As one of the documentarians in the broader community, I episodically attempt to make sense of, clean up, and (hopefully) improve the various sets of documentation. Currently, I am poking primarily at the wiki, and I find myself in a long series of circular tangles of information that render a solution daunting (to say the least).

There are two entries on Online Quotes in the FAQ; these refer to each other and to a separate page on the wiki. The separate wiki page is a mess of highly technical information that has nothing to do with the FAQ questions, and offers no help in that regard (making the references from the FAQ less than helpful). Furthermore, both the Guide and the Help have separate, essentially complete descriptions of setting up online quotes.

Any rightful attempt at ensuring that online quoting is properly and carefully documented requires that *every* one of these sources be updated and coordinated with the others. This turns out to be exceedingly challenging, especially given that it’s not entirely clear which source should contain which data. To me (admittedly a “Concepts” kind of guy), the fullest description of setup and management should go into the Guide at section 9.6. However, the Help at section 5.4.1.1 includes another essentially full description of setup and management; presumably this entry should focus on the “This button does This action” kind of information (since that is what I understand is supposed to be the primary purpose of the Help). And where, in all this, do the different pieces on the wiki fit in?

Attempting to shepherd any rationalization of these resources through the process is painful and time-consuming.

I will note that the challenge described here repeats itself time and time again, in all manner of subject areas in the documentation, leaving the documentation in a disorganized state.

Here is my proposed action plan:

1) Edit the Guide to include background, setup and management of online quoting. This section will explain F::Q, its relation to GnuCash, installation, and maintenance. 
2) Edit the Help to remove information covered in the Guide, and add references to the Guide. Determining which pieces are context versus background will be difficult, BTW.
3) Replace FAQ questions with references to “Online Quotes” pages and the Guide, and move all detail to those locations.
4) Rewrite “Online Quotes” to be geared first to troubleshooting for the end user (rather than whatever it currently is).

Unclear to me, however, is the extent to which GnuCash should document Finance::Quote and its functionality. Technically, F::Q is an external project, and so GnuCash should point to F::Q for detailed help, rather than write and provide it. However, it is clear that there is a disconnect between the help provided by F::Q, and the technical skill level of many GnuCash users. I’m not sure where to draw the line here.

Because of this, I believe it might be best to keep technical aspects of F::Q on our wiki page (at “Online Quotes”), since they can change without GnuCash control. Changing the wiki to reflect current F::Q behavior is quicker and easier than trying to get those changes into the Help or Guide.

Comments and advice are welcome.

David