Document Update Instructions have been revised

[Frank H. Ellenberger]

Hi all,

just a few ideas:
I found by accident the 10 years old
http://wiki.gnucash.org/wiki/Concept_Guide_draft/Overview ff., which is
an example for using subpages in a template
http://wiki.gnucash.org/wiki/Template:Cgtoc .

Don't confuse it with the more recent
http://wiki.gnucash.org/wiki/Concept_Guide which is more a todo list and
ancestor of the Document Update Instructions

Recently I was asking myself and Gert, if we should move the nice
written sections about
#The_Make_Utility
#Step_3_Generate_configure_Script
#Step_4_Make_a_Build_Directory_Structure_and_the_Makefiles
in the basic existing page http://wiki.gnucash.org/wiki/Build_System
or a new page Autotools and linking it from Building_Gnucash and
Translation, too.
That would have the benefit there would be only one page to maintain
almost everything about the autotools components. OTOH some users could
be distracted by the jumping between the pages.

Your opinion?

I understand that the pull request is the adequate way for a longtime
contributor on the mailing list like  you, David. But it would be too
much overhead to create an github account, a ssh key, ... to send a
patch for a typo by a random reader.

Regards
Frank

Am 22.01.2017 um 01:35 schrieb 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