[GNC-dev] Documentation--What else?

Fri Sep 7 19:55:39 EDT 2018

David,

I checked your Github repository and it looks good.

I agree with Geert, your plan for Online Quotes seems sound.

I haven’t reviewed the wiki Online Quotes page; if there’s material there about the F::Q API, you may safely remove it because that’s duplicated in the F::Q documentation. Any other technical information should stay or at least be carefully reviewed before removal. 

Regards,
John Ralls

> On Sep 7, 2018, at 1:24 PM, David T. via gnucash-devel <gnucash-devel at gnucash.org> wrote:
> 
> Ha. That means I have to figure out how to get my local repository working again….
> 
> [some time later]
> 
> OK, so I googled “force upstream into fork” and found some resources that seem to have fixed things for me. The commands I issued were:
> 
> DHT-Retina:gnucash-docs david$ git fetch upstream
> DHT-Retina:gnucash-docs david$ git reset --hard upstream/maint
> HEAD is now at ecd868b Fix xmllint error
> DHT-Retina:gnucash-docs david$ git push origin maint --force
> Counting objects: 99, done.
> Delta compression using up to 8 threads.
> Compressing objects: 100% (99/99), done.
> Writing objects: 100% (99/99), 95.66 KiB | 0 bytes/s, done.
> Total 99 (delta 69), reused 0 (delta 0)
> remote: Resolving deltas: 100% (69/69), completed with 15 local objects.
> To https://github.com/sunfish62/gnucash-docs
> + 4de1289...ecd868b maint -> maint (forced update)
> 
> If I understand it correctly, the first command brings in upstream (github.com/gnucash/gnucash-docs <http://github.com/gnucash/gnucash-docs>), the second force-resets my local (computer) repo to match upstream/maint, and the last pushes my (now-updated) local repo to my github fork. Do I have this right?
> 
> This appears to have done the trick; I see Geert’s final xmllint changes to ch_basics.xml on my local system, and github says that my fork is even with Gnucash-docs.
> 
> Is there another way that I can verify this? After all, I have remarkably bad luck when it comes to git…
> 
> David
> 
> 
>> On Sep 7, 2018, at 12:54 PM, Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
>> 
>> 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
>> 
>> 
>> 
>> 
> 
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel