Re: Document Update Instructions have been revised

[Frank H. Ellenberger]

Hi,

Am 23.01.2017 um 23:33 schrieb Chris Good:
> Developers are less likely to be confused by jumping around the wiki than 
> potential documenters.

But from my POV the weakest affected group are the translators as they
are usually no native english speakers.

Should we really move it to Translation and link the other pages? ;-)

Yes, currently Build_System is a stub - more or less a reminder "we
could explain it here in detail and link the other places":
* Building* (Techies),
* Document* (Docu writers, mostly native speakers) and
* Translation (foreign writers)

Regards
Frank
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

RE: Document Update Instructions have been revised

[Chris Good]

> -Original Message-
> From: Frank H. Ellenberger [mailto:frank.h.ellenber...@gmail.com]
> Sent: Monday, 23 January 2017 7:09 PM
> To: Chris Good ; 'David T.'
> 
> Cc: 'GnuCash Developers' 
> 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 
> >> Cc: GnuCash Developers 
> >> 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 
> >> wrote:
> >>>
> >>> Hi,
> >>>
> >>>
> >>>
> >>> I've finished updating the wiki Document Update Instructions [1] to
> >>> include instructions for using 'make' rather than xmllint and
> >>> xsltproc

Re: Wiki URL

[Derek Atkins]

Hi,

"Frank H. Ellenberger"  writes:

> I would split it in 2 sections:
>
> (Mostly) for
> * Users
> :* Wiki
> :* Mailing lists
> :* IRC logs
> :* Home Page
> * Developers
> :* API
> :* GitHub

I reordered it this way (but did not explicitly split it into multiple
sections).

> ~Frank

-derek

-- 
   Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
   Member, MIT Student Information Processing Board  (SIPB)
   URL: http://web.mit.edu/warlord/PP-ASEL-IA N1NWH
   warl...@mit.eduPGP key available
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Moving Forward with Documentation Bug 687820

[David T. via gnucash-devel]

Hello,

Nearly five years ago, I created Bug 687820 in a more innocent time. In that 
bug, I outlined an ambitious plan to restructure the Tutorial and Concepts 
Guide, which received a modicum of positive support when I initially submitted 
it.  

At this time, I think that I am comfortable enough with the editorial process 
to actively begin this migration. To that end, I would like to proceed by 
submitting separate bugs for each of the large changes I originally wrapped in 
that one bug. The first of these is Bug 777318, in which I propose merging two 
Business chapters. I welcome feedback here or on the bugs in question in 
regards to the bugs.

TIA,
David
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Document Update Instructions have been revised

[David T. via gnucash-devel]

Hi Frank,

> On Jan 23, 2017, at 1:09 PM, Frank H. Ellenberger 
>  wrote:
> 
> 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 .
> 

Wow. I think that set of pages should probably just go away? The Concept Guide 
has moved well beyond these drafts.


> 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

The to do list is also dated, but might still be of use. I don’t know whether 
it should be updated or scrapped.

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

The Build System page is too technically-focused and too sparse for my limited 
abilities, and in the context of the docs process, it won’t be of help to the 
people who want only to update the docs (that’s me). 

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

First, setting up the github account was pretty simple (even for me). 

Second, there is simply no way that a “random reader” is EVER going to make a 
change to the documentation. There is a HUGE jump from typing a Word document 
or an email to using a version control system to edit and manage XML files from 
a remote repository. I know, because I have struggled long and hard to 
understand the little of this all that I do. As I said earlier, as a 
non-programmer, I can say that the ONLY way I’ve been able to contribute 
consistently has been through the git pull process.

David

> 
> Regards
> Frank

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: 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:sunfis...@yahoo.com]
>> Sent: Saturday, 21 January 2017 6:38 PM
>> To: Chris Good 
>> Cc: GnuCash Developers 
>> 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 
>> 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