> On Jan 18, 2017, at 8:06 AM, Chris Good <chris.g...@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@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
