[GNC-dev] Documentation--What else?

[David T.]

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
> 
> 
> 
>