Document Update Instructions have been revised

[David T.]

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
> 
> 
>