> -----Original Message----- > From: Frank H. Ellenberger [mailto:frank.h.ellenber...@gmail.com] > Sent: Monday, 23 January 2017 7:09 PM > To: Chris Good <chris.g...@ozemail.com.au>; 'David T.' > <sunfis...@yahoo.com> > Cc: 'GnuCash Developers' <gnucash-devel@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: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 >
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
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
