[GNC] Thoughts on Online Quotes documentation

[Jim DeLaHunt]

I recently had a problem[1] with getting online quotes from GnuCash 5.5 
on macOS. It caused me to reflect on some shortcomings[2] of the GnuCash 
wiki page on Online Quotes[3]. This message is an attempt to capture 
some thoughts on how that the Online Quotes documentation might be 
improved. Actually doing the improvement is a big job. I don't promise 
to do it myself right now.

A general observation: the top of Online Quotes is big and sprawling, 
with many facets:

 1. The task: how to install, how to update, how to configure stock
    entries, how to get quotes, how to get historical prices
 2. The components of the online quotes machinery:
     1. the Perl interpreter
     2. Finance::Quote and the Perl modules on which it depends
     3. GnuCash's tools for installing Finance::Quote
     4. System installs vs package manager installs of Perl & modules
        (I'm looking at you, Homebrew and MacPorts)
 3. The different platforms — Unix, macOS, Apple Silicon vs x86_64 on
    macOS, Windows, different versions of Windows. There are variants of
    many of the sections for the various platforms.
 4. The different data sources and symbols quirks for each
 5. Troubleshooting
 6. Versions of GnuCash: the facilities for online quotes have changed
    from major version to major version of GnuCash, and that content is
    folded together into one wiki page.
 7. The documentation locations: the Online Quotes wiki page[3], and two
    places in the GnuCash manual[4][5], aspire to be well coordinated
    but have evolved away from that.

The current Online Quotes wiki page is 108,503 bytes mixing together 
#1-#6 above. That is so big and confusing to be hard to navigate.

One short term action could be to agree how to refactor. Then various 
people can take incremental refactoring steps.

In particular, I suggest we consider splitting Online Quotes by GnuCash 
version groups, then by platform. Version groups are ranges of GnuCash 
versions, and change where the Online Quotes behaviour in GnuCash 
changed: current is GnuCash 5.x, previous is 4.x, before that is 3.11 
and earlier. Platform is probably: macOS (inc Homebrew, Gnucash), 
Windows, Unix, cross-platform.

Imagine the article <wiki.gnucash.org/wiki/Online_Quotes> refers to 
sub-articles like 
<wiki.gnucash.org/wiki/Online_Quotes/current/macOS/Installation>, 
<wiki.gnucash.org/wiki/Online_Quotes/4.x/Unix/Troubleshooting>, 
<wiki.gnucash.org/wiki/Online_Quotes/current/all/Retrieving>. (Those 
names are for illustration only. Getting good names will probably take 
some work.)

Another short-term action is to move content out of the wiki article and 
into the GnuCash Manual, especially for Installation. The article says, 
"Before you continue read the Official Documentation... We try to reduce 
redundancy." Let's take that seriously.

Hopefully these notes contribute to whatever improvement project gets done.
Best regards,
    —Jim DeLaHunt

[1] [GNC] GnuCash 5.5 (macOS) can't get quotes, because it doesn't see 
JSON::Parse,  Sat, 23 Dec 2023 12:30:43 -0800 
<https://www.mail-archive.com/gnucash-user@gnucash.org/msg38877.html>

[2] ibid thread,  Sun, 24 Dec 2023 11:31:44 -0800 
<https://www.mail-archive.com/gnucash-user@gnucash.org/msg38883.html>

[3] <https://wiki.gnucash.org/wiki/Online_Quotes>

[4] GnuCash Manual, 5.4.2. "Steps to enable Online Quotes updating" 
<https://www.gnucash.org/docs/v5/C/gnucash-manual//acct-create.html#accts-online-quotes>

[5] GnuCash Manual, Chapter 11. "Setting Up the Quote Retrieval" 
<https://www.gnucash.org/docs/v5/C/gnucash-manual/finance-quote.html>