Documentation translators: Changed para in ch_oview

Tue Aug 9 07:59:10 EDT 2016

Geert,

> On Aug 9, 2016, at 2:19 PM, Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
> 
> On Tuesday 09 August 2016 13:37:02 David T. wrote:
> > Geert and Frank,
> > 
> > I understand that these aspects of software development are clear and
> > easy for you; suffice to say they are not for me. I do not wish to
> > start any long discussion about the mechanisms for implementing
> > changes to GnuCash’s code and documentation; they have been hashed
> > out many times before. My position has been that I am first and
> > foremost a skilled editor; my abilities in the use of programming
> > tools are epic in their limitations. The use of such tools for the
> > documetation has been and continues to be a significant impediment to
> > my contributing to the improvement of the docs.
> > 
> > Regardless, I have been under the impression (propagated on the user
> > list regularly) that changes should be submitted to BugZilla so that
> > they can be tracked and followed through. I was suggesting that
> > presenting the bug fix solely through git-whatever represents a
> > change in update procedures, and I wanted to know whether *that* is
> > going to be the preferred method in the future.
> > 
> Ok, I had to re-read this a couple of times to get your point.
>  
> For some time now we are accepting changes in two ways: either as an attachment in bugzilla or as a pull request in github. The submitter can choose freely based on his/her preference, but is not required to submit to both.
>  
> So yes, there can be changes that are only proposed via github.
>  
> Thanks to your heads up I do realize now this can make it harder for non-developers to give feedback on those changes. So this can raise the bar for documentation changes review.
>  
> On the other hand, I do want to understand in how far github solely as a review board is crippling you. You didn't answer my direct questions related to Frank's request.

Frank’s first request read as follows: "So I ask you kindly, to review commit e4c8bae - Replace the confusing Release_Schedule link by 2.6-release-tour and website”

That, simply put, means absolutely nothing to me, and I have no way to even know how to find the change, since I do not know how to use git-whatever. Hence, my request, which I thought was respectful.

>  
> You can submit a patch to bugzilla, so I assume you can more or less interpret such a patch file as well ? (That may be a false assumption I know hence the question mark). If not the rest below makes no sense.

I believe that when you say “You can submit a patch” that you mean that “You are able to submit a patch.” While it is true that I have submitted patches to bugzilla, each such submission has come at a great deal of trial and challenge—not just for me, but also for the development team (cf. threads “Fun with Git” and “Fun with Git, Redux” in February and August 2015). FWIW, each time I have submitted a patch, I have started from an entirely fresh installation of git-whatever and whatever development platform software is popular at the time, and a fresh installation of GnuCash’s material. This is a major impediment to my contributing more regularly. Honestly, I don’t enjoy such challenges.

>  
> So if you are presented with the changes in such a format, would you be able to read it and understand what's ok and what needs improvement ?

Yes, with the subsequent direct link to the changeset, I can read the changes. I will note that the editorial process is ill-served by the patch method of propagating changes; editorial changes are IMHO best viewed in context; the patch method strips away the context. Whenever I consider a patch in docs, I have to open the current doc in another window to see what the change is actually going to do.

> If you find such areas, as far as I'm concerned, you can post your feedback on the mailing list right here. Or you can click on the blue plus sign on github right in front of the line you want to leave feedback on 

I don’t see any blue plus sign, unfortunately. 

> and just write it down there in the text box that appears. I'm not sure how much easier giving feedback can become (all assuming a patch file can be understood of course).

As for the modification that Frank is offering, I will note that there is a bug that I filed in bugzilla (743672) proposing that this section be moved in its entirety to an appendix. Perhaps now would be the time to consider that bug? I don’t see the point of having the What’s new section in a section promoting the features of GnuCash to a new user.

David

>  
> Regards,
>  
> Geert  
>  
> > David
> > 
> > > On Aug 9, 2016, at 12:48 PM, Geert Janssens
> > > <geert.gnucash at kobaltwit.be <mailto:geert.gnucash at kobaltwit.be>> wrote:> 
> > > On Tuesday 09 August 2016 09:46:00 David T. via gnucash-devel wrote:
> > > > Frank,
> > > > 
> > > > As a git-challenged documentation contributor (I imagine my
> > > > git-clutziness is well-documented), is there a non-git way you
> > > > could
> > > > present your change, so that I might examine it and maybe comment?
> > > 
> > > Can you read a diff file or a patch file ? In that case you can look
> > > at the following webpage (on github):
> > > https://github.com/Gnucash/gnucash-docs/commit/e4c8baef5042cd50268b <https://github.com/Gnucash/gnucash-docs/commit/e4c8baef5042cd50268b>
> > > 0c5eaa36951e0c37278e
> > > <https://github.com/Gnucash/gnucash-docs/commit/e4c8baef5042cd50268 <https://github.com/Gnucash/gnucash-docs/commit/e4c8baef5042cd50268>
> > > b0c5eaa36951e0c37278e>
> > > 
> > > Note that due to the way the Italian translation is set up, this
> > > commit contains a huge list of changes to the Italian translation
> > > file (it.po). Unless you want to take on the Italian translation,
> > > you can skip all these changes.
> > > 
> > > Otherwise what would you suggest to make it easier on you ?
> > > 
> > > Note I don't expect you to understand git and send patches in git
> > > compatible format. The github website on the other hand i more than
> > > just a collector of git commits. It comes with several useful
> > > "reporting" features. One of them is it can visualize the changes
> > > in one single commit in a way that's IMO fairly readable without
> > > understanding git. I hope that part works for you as well. I would
> > > no doubt have been more useful to you if Frank provided you with a
> > > link to click on.> 
> > > > To the list:
> > > > Is the group hoping to move away from bugs on Bugzilla in favor of
> > > > an
> > > > all-git process? ISTM that recent comments on the lists hint at
> > > > that
> > > > direction. As I note above, this can act as a barrier to some of
> > > > us
> > > > technologically challenged individuals. Perhaps it is not such a
> > > > big
> > > > deal for code developers, but documentation involves a much
> > > > different
> > > > contributor base.
> > > 
> > > You're confusing git and github here, but that's ok. Short
> > > clarification: git is only a mechanism to store source changes in a
> > > way the history remains manageable. It's very powerful for that,
> > > which makes it challenging to learn to use efficiently. In itself
> > > it lacks all kinds of other tools required for development, like a
> > > feature/bug tracker, wiki pages,... Github is one website that has
> > > set up all these things around git and much more. It's goal is to
> > > provide a more convenient way of working with git by providing a
> > > graphical interface, and some additional useful features wrt
> > > collaboration.
> > > 
> > > Having said all that there is no intention I know of to move to a
> > > purely github based process - particularly not for the
> > > documentation - even though some of it's features are very handy.
> > > You are still welcome to provide patches via bugzilla (we're not
> > > even using github's issue tracker, hah! ;) ).
> > > 
> > > Regards,
> > > 
> > > Geert