> -----Original Message----- > From: David T. [mailto:sunfis...@yahoo.com] > Sent: Saturday, 21 January 2017 6:38 PM > To: Chris Good <chris.g...@ozemail.com.au> > Cc: GnuCash Developers <gnucash-devel@gnucash.org> > Subject: Re: Document Update Instructions have been revised > > Chris, Geert, > > I have to admit that I have put off reading through the changes that you’ve > collectively put in on this wiki page, in part because I am *that* > contributor— > you know, the one who barely understands what he is doing, and is wary of > changing the way he does something for fear that it will break and never > work again. > > I have begun to work through this page one more time, and I will no doubt > have changes and suggestions later on. I will refer to my sentence above, > however, and note that my editorial inclinations are limited by my limited > understanding of the technologies and expectations for this process > generally. > > I have a few top level comments: > > A - This page has gotten quite large. Should it be broken into smaller pieces? > > B - I would like to see this page separate out the different aspects of the > process more cleanly. Currently, it seems that the set up of the technologies, > the application of the technologies, and the practices we use are all > intermingled. This makes it harder to focus on one aspect. For example, > Steps 2-5 should be separated out into a separate page on setting up Git for > use with documentation. > > C - I think the Preface should outline as simply as possible the overall > process, > which I understand to be: > > 1) Contributors propose changes using Bugzilla. > 2) Contributors use a VCS (git), to make these changes locally. > 3) Changes are validated locally. > 4) Contributors submit these changes for approval. > 5) Changes are approved and incorporated into the doc set. > > This overview could then be used to structure the remaining sections. > > I think that the information that currently resides in the Preface is useful, > however, and I’d like to see it moved into other areas as appropriate. > > D - Upon initial examination, I see that all reference to how it used to be > done (i.e., the individual xslt and xmllint commands) has been removed from > the page. While I understand that you two believe that this is the right way > to > move forward, it leaves me in a quandary. I already have a local copy, and I > know that I can issue some commands to check and compile my local copy, > but I always refer back to the wiki for the exact commands, which you’ve > removed. I would prefer that some inclusion of these other methods be > mentioned in some way. > > I began to make some of these changes myself, but given my limited abilities > with these processes, I thought it better to discuss the changes here before > unilaterally (and ill-informedly) making the changes directly. > > David > > > On Jan 17, 2017, at 5:16 AM, Chris Good <chris.g...@ozemail.com.au> > wrote: > > > > Hi, > > > > > > > > I've finished updating the wiki Document Update Instructions [1] to > > include instructions for using 'make' rather than xmllint and xsltproc > directly. > > > > Thank you very much Geert for all the info. > > > > > > > > [1] http://wiki.gnucash.org/wiki/Documentation_Update_Instructions > > > > > > > > Regards, Chris Good
Hi David, A - IMHO I don't think this page is too large. It is quite easy to navigate using the index at the top. It would be annoying to have to jump to multiple pages. B - I agree it could be better structured. I don't think it needs a new page. If you're going to put 3.2 to 3.5 into a separate git set up section, it would be good if you could include some instructions on how to start a new modification (including rebasing) having already set up git and your build directory structure previously. I previously created Git_For_Newbies with the idea that new users should really be using that for all the git stuff (using Pull Requests instead of Patches if possible). Git_For_Newbies applies equally to the documentation as to the programs. I haven't gotten around to fixing Documentation_Update_Instructions yet. If you can, Great! :-) It may be that much of Git_For_Newbies needs to be brought into Documentation_Update_Instructions but changed to specifically refer to the documentation. But that seems like a lot of duplication... C - Having an additional outline as you suggest may be helpful, although the index already gives a 1 page summary - on my new 27" monitor anyway :-). I'm not sure I agree with moving the stuff already in the Preface into other areas. I think it is useful to get some detail of what is involved before reading everything. D - Why do you need the original xmllint + xsltproc commands? Don't the 'make' commands work for you? In my experience, 'make' is installed by default in all the Linux distros I've used (not many I admit). Is that not the case in Mac OSX? You can create a build directory structure within your existing local repo. I thought about leaving the original commands in the documentation but couldn't think of any reason they should be needed. They would just confuse new documenters. Regards, Chris Good
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
