Document Update Instructions have been revised

Sun Jan 22 02:28:59 EST 2017

From: David T. [mailto:sunfish62 at yahoo.com] 
Sent: Sunday, 22 January 2017 5:30 AM
To: Chris Good <chris.good at ozemail.com.au>
Cc: Geert Janssens <geert.gnucash at kobaltwit.be>; GnuCash Developers <gnucash-devel at gnucash.org>
Subject: Re: Document Update Instructions have been revised

On Jan 18, 2017, at 8:06 AM, Chris Good <chris.good at ozemail.com.au <mailto:chris.good at ozemail.com.au> > wrote:

* Lastly you describe how to format a patch. While this is certainly one

of the

accepted methods, it may be interesting to document how to make a pull
request as well.

That's it. Again, thanks for all the effort you spent on this so far!

Regards,

Geert

It seems to me that this instruction set is meant for new contributors to the documentation. Personally, I think such a set of instructions should focus primarily on ONE method for contributing, with passing mention of other possibilities. As I understand it, the git way is the currently-preferred method for offering contributions, and IMHO, this wiki page should focus primarily on that. Passing mention of other methods can be included for those who already have the understanding of the technologies. Thus, the discussions about formatting a patch and attaching it to the bug could be mentioned in passing, while the git pull request method could be brought forward and promoted.

In the same spirit of giving simpler advice to new contributors, I would prefer that the git process described here refer to the other Git page (wiki.gnucash.org/wiki/Git <http://wiki.gnucash.org/wiki/Git> ), which I think should be cleaned up by someone who knows more about git than I do. 

FWIW, I think the other Git page should focus on one preferred git modality, said modality being the one where contributors fork the main GC repository on github.com <http://github.com> , push their changes to that fork, and then issue pull requests to the main repo. Again, other options could be mentioned in passing, but the focus should be on the GnuCash Preferred Method.

As for the whole “testing the help on Linux” section, as a Mac user, I have NEVER attempted any of this, and if it is an important part of the documentation creation process, then I haven’t  done it correctly ever. Since I have been successfully adding to the documentation for a while now, I can assume that this section is, in fact, superfluous to the actual documentation update process. I would propose moving it into some other area of the wiki, perhaps with an advanced Linux developer’s page, where true geeks (I say this with admiration) can plumb the depths of providing this added Linux functionality. 

David

Hi Geert,

Thanks for reviewing my work and adding extra suggestions. I really enjoy
learning more from your insights. I like to know, at least generally, 'why',
as well as 'how'.
I totally agree your suggestions would be helpful to new documenters. I'm a
little concerned that the bulk of this page could be a little off-putting.
However, I think it is better to have too much info than not enough.
I would like to point out that your suggestions are mostly changes to things
other people wrote. :-)

Originally, I myself started to try to modify the documentation on Windows
but soon thought it was not possible (or at least too difficult), and
changed to Linux.
People who are not familiar with Linux and virtual machines would probably
like more guidance on this.
I have since found that xmllint.exe & xsltproc.exe are in
c:\strawberry\c\bin so that may help. Maybe an msys (or cygwin?) environment
is not needed. I know practically nothing about msys or cygwin. If anyone
else can add anything about updating the documentation on Windows or Mac,
I'd like to hear it.

Re the various translations:
I only speak 1 language, English (Australian) fluently, and some will argue
about that, so it has never really mattered to me, but...
Is it true that the non-English versions of the documentation are
translations of the English documentation?
If so, is this 'policy' or just how it has worked out?
I could imaging that different translations could have totally unique
sections to cater for localisations.

I agree it should be made clearer that it is only necessary to build and
install a development version of GnuCash (programs) if one needs to test
context help for features that are only in a more recent version than
already installed. That section has always been confusing to me.

'Step 2 Git Clone' links to info about using pull requests instead of
patches.
I'll add similar references to the start of ' Step 15 Prepare your Patch'.

Regards, Chris Good
_______________________________________________
gnucash-devel mailing list
gnucash-devel at gnucash.org <mailto:gnucash-devel at gnucash.org> 
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Hi David,

You seem to be a little confused between git and github. Both the patch and pull request methods use git on your PC.

Both the patch and pull request methods get the local repo from github. Only the pull request method uses github for the submitting of the modification request. A github pull request is the method the developers currently prefer for offering contributions.

I think you already know that, but as we’re discussing fairly time consuming changes, we should be clear.

Yes, the Documentation Update Instructions are aimed at new contributors. For non-technical people, submitting a patch is the easiest way, so that is historically the primary focus of this page. I think this is so as not to confuse them by making them jump to another page.

Maybe others will disagree but I don’t think changing the primary focus of this page from patches to pull requests is really the best use of your time. :-)

It seems people are skipping the reference to http://wiki.gnucash.org/wiki/Git_For_Newbies from http://wiki.gnucash.org/wiki/Documentation_Update_Instructions#Step_2_Git_Clone. Do you think it should be made clearer that this discusses Patches and Pull Request procedures as well as basic git commands?

I did in the past try to improve wiki.gnucash.org/wiki/Git <http://wiki.gnucash.org/wiki/Git>  but this was deemed to be a backward step for git experts, and thus I put my changes into new page Git_For_Newbies instead.

Re: “testing the help on Linux”:

This is only really necessary if testing context sensitive help. (I.e. invoking a particular help section using the F1 key from within GnuCash) where that invocation is only in new code, so cannot be tested from an already existing GnuCash installation. Geert has recently made that clearer. I think this page is an appropriate place for this info.

Regards, Chris Good

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4817 bytes
Desc: not available
URL: <http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20170122/5a8d4b54/attachment.p7s>