Re: [GNC-dev] Documentation--What else?

[David T. via gnucash-devel]

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

David

> On Sep 7, 2018, at 7:55 PM, John Ralls  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 
>>  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 ), 
>> 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  
>>> 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, 

Re: [GNC-dev] Documentation--What else?

[John Ralls]

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

Re: [GNC-dev] Documentation--What else?

[David T. via gnucash-devel]

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

Re: [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@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel




___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel