[GNC-dev] Documentation--What else?

[Geert Janssens]

That reads like a good plan.

I'm all for deduplication. I agree with your assessment of what help and guide 
should be. And that the guide should be the general documentation with 
troubleshooting explained in the wiki. Troubleshooting tends to change more 
quickly than base documentation.

I also think it's a good idea to keep an entry point on Online Quotes on the 
FAQ.

So a +1 on all accounts.

Geert

Op vrijdag 7 september 2018 17:47:55 CEST schreef David T. via gnucash-devel:
> 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
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel