Document Update Instructions have been revised

[Chris Good]

> -----Original Message-----
> From: David T. [mailto:sunfish62 at yahoo.com]
> Sent: Saturday, 21 January 2017 6:38 PM
> To: Chris Good <chris.good at ozemail.com.au>
> Cc: GnuCash Developers <gnucash-devel at 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.good at 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
-------------- 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/eeed4171/attachment.p7s>