[GNC-dev] Documentation--What else?

Sat Sep 8 10:36:40 EDT 2018

Thanks John for the confirmation on my efforts to realign my repo.

David

> On Sep 7, 2018, at 7:55 PM, John Ralls <jralls at ceridwen.us> wrote:
> 
> 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
> 