Document Update Instructions have been revised

[Chris Good]

> -----Original Message-----
> From: Frank H. Ellenberger [mailto:frank.h.ellenberger at gmail.com]
> Sent: Monday, 23 January 2017 7:09 PM
> To: Chris Good <chris.good at ozemail.com.au>; 'David T.'
> <sunfish62 at yahoo.com>
> Cc: 'GnuCash Developers' <gnucash-devel at gnucash.org>
> Subject: Re: Document Update Instructions have been revised
> 
> 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
> 

Hi Frank,

http://wiki.gnucash.org/wiki/Concept_Guide_draft/Overview is an interesting example to keep in mind.

I agree we should eliminate duplication where possible.
I think maybe we should leave the Documentation Update Instructions as is and link to the about #The_Make_Utility, #Step_3_Generate_configure_Script & #Step_4_Make_a_Build_Directory_Structure_and_the_Makefiles sections in it from http://wiki.gnucash.org/wiki/Build_System.
Developers are less likely to be confused by jumping around the wiki than potential 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/20170124/3ea0c4a9/attachment.p7s>