Re: [GNC-dev] Wiki Home page

[Frank H. Ellenberger]

At least and more important: You are back again. :-)

Am 18.08.2018 um 17:42 schrieb D via gnucash-devel:
> Adrien, John, Frank, and others,
> 
> Thank you all for your considered input and forbearance. In looking over the 
> wiki-related threads I've generated in the last couple of days, I can clearly 
> see both my petulance and pettiness on them, and I apologize.
> 
> Obviously, encouraging people to get involved is most important, and whether 
> the verb used to describe this is "developing" or "improving" is not so 
> important.
> 
> I apologize again for cluttering the list.
> 
> David T.
> 
> On August 18, 2018, at 7:03 AM, John Ralls  wrote:
> 
> The other application project I’m involved with, Gramps (a genealogical 
> project manager) uses a wiki with restricted editing for its manual.
> 
> No, no one has ever suggested switching to a CMS for www.gnucash.org 
> . I don’t think that there would be any payoff for 
> the effort and it would stop us using git to manage revisions.
> 
> Regards,
> John Ralls
> 
>> On Aug 18, 2018, at 4:57 AM, Adrien Monteleone 
>>  wrote:
>>
>> From a cursory look at other FOSS projects:
>>
>> LibreOffice has an “Improve It” menu on their site, with an entry labeled 
>> “Docs Team”. They utilize a wiki and printable WYSIWYG produced using LO 
>> itself. (probably the lowest entry barriers of any project save for Mozilla)
>>
>> GIMP has a “Participate” menu and then a link for “add Documentation” (but 
>> that took me to the docs, not how to contribute. I had to go to their 
>> generic developers page to find anything on contributing to the docs) It 
>> appears they currently use DocBook XML/git but are looking to move to 
>> something else using markdown.
>>
>> Inkscape has “Contribute” “Learn” “Community” “Develop” menu entries on 
>> their site. Strangely, how to help with documentation seems a bit hidden, 
>> but apparently, that’s because it seems to be all via their website CMS. 
>> Details info might be hidden behind their documentation mailing list they 
>> direct everyone to, but I don’t see any page on what is involved in the doc 
>> process itself.
>>
>> Thunderbird & Firefox have a “Get Involved” link and then a simple 
>> “Documentation” heading and a “Contributing to Documentation” subsection. 
>> They utilize a wiki apparently exclusively. (with official help forums for 
>> users instead of a mailing list which employs ’sticky’ articles people can 
>> write - something I think GnuCash could benefit greatly from, especially 
>> just for users.)
>>
>> Gnome - has a “Get Involved” link, then a simple “Documentation” heading 
>> with “Contribute to the documentation team” link. They seem to use Mallard, 
>> an XML editor and Git.
>>
>> Arch - yes, that Arch, uses a wiki. (integrated help is of course in the 
>> form of man pages as part of their regular build system)
>>
>> So perhaps taking a cue from that, a simple “Contributing to Documentation”, 
>> “Help with Documentation” or a simple “Documentation” heading/link is just 
>> fine. It did seem that those projects that used more complicated tools than 
>> wiki/CMS hid their actual process behind several links or I had to go to the 
>> developer section to find anything. I’m not suggesting GnuCash should bury 
>> info however.
>>
>> I see on the website, GnuCash has a simple “Writing Documentation” link and 
>> the page looks pretty direct and straightforward. The Wiki page is certainly 
>> more involved, but I don’t think the title “Improving” here is misleading. 
>> The only thing I see missing on either page is any hint that the wiki or the 
>> website are also documentation projects, or how to get involved with them, 
>> and at least the former has a lower entry barrier. (Has there been any 
>> discussion of moving to a CMS for the website?)
>>
>> Just some thoughts...
>>
>> Regards,
>> Adrien
>>
>>
>>
>>> On Aug 18, 2018, at 1:42 AM, David T. via gnucash-devel 
>>>  wrote:
>>>
>>> Frank,
>>>
>>> You imply that the use of Eclipse somehow renders the documentation process 
>>> simple enough for a user to identify a typo and get it fixed. I flat out 
>>> disagree, and I think that using disingenuous language on the wiki home 
>>> page is not going to change the reality: implementing a change in the 
>>> documentation is a Process.
>>>
>>> I still think the heading should be reverted to “Developing the 
>>> Documentation”, and I am copying gnucash-devel as you requested.
>>>
>>> David
>>>
>>>
 On Aug 17, 2018, at 11:23 AM, Frank H. Ellenberger 
  wrote:

 Hi David,

 Am 16.08.2018 um 20:52 schrieb David T.:
> Frank,
>
> As you will see on gnucash-devel, I had reason to examine the wiki home 
> page today, and noticed some of the changes you have implemented there 
> over the last year or so. I wanted to discuss off list with you one of 
> those changes.
>
> You changed “Developing the Documentation” to “Improving the 
> 

Re: [GNC-dev] Main WIki Page edit

[D via gnucash-devel]

The glossary entry has historically been included separately on this page. When 
I last suggested changes for the page, it didn't occur to me to remove that 
separate section and incorporate references to them (there are two glossaries: 
one in the Guide, and the one on the wiki, each with slightly didn't vintage) 
in other locations.

Incorporating these references into other sections makes sense to me. It 
simplifies the main page structure a little, and reflects the fact that the 
glossaries are part of the Guide and wiki, respectively.

I'll look into a rewrite, and send it in for adjustment in the next few days.

David T.

On August 18, 2018, at 7:15 AM, Adrien Monteleone 
 wrote:

In combination with making the T glossary sentence a part the Official 
documentation paragraph, I think the second sentence should be moved down to 
the Developer Documentation paragraph.

Also, the following line needs a number correction:

"The Documentation page on the gnucash.org website also contains ~~this~~ 
_these_ documents in”

I’d do either myself, but I see the main page is above my pay grade. (I’m sure 
for very good reason)

Regards,
Adrien

> On Aug 18, 2018, at 8:53 AM, John Ralls  wrote:
> 
> 
> 
>> On Aug 17, 2018, at 11:45 PM, David T. via gnucash-devel 
>>  wrote:
>> 
>> 
>> 
>>> On Aug 17, 2018, at 11:29 AM, Frank H. Ellenberger 
>>>  wrote:
>>> 
>>> Am 16.08.2018 um 20:37 schrieb David T. via gnucash-devel:
 Hello,
 
 I was reviewing the Wiki today to try to figure out where a page on the 
 SQL formats might get attached, and I noticed a change to the Glossary 
 section that makes for awkward English.
 
 As currently entered, the section reads:
 
 Above GnuCash Tutorial and Concepts Guide includes a comprehensive 
 Glossary: 
 [https://www.gnucash.org/docs/v2.6/C/gnucash-guide/gnc-gloss.html 
 Released] or [https://code.gnucash.org/docs/C/gnucash-guide/gnc-gloss.html 
 Maintainer] version.
 
 However, it used to say:
 
 The GnuCash Tutorial and Concepts Guide includes a comprehensive Glossary: 
 [https://www.gnucash.org/docs/v2.6/C/gnucash-guide/gnc-gloss.html 
 Released] or [https://code.gnucash.org/docs/C/gnucash-guide/gnc-gloss.html 
 Maintainer] version.
 
 I would like to ask that someone with edit permissions on the wiki home 
 page to please change the word “Above” back to “The” to make the section 
 read more idiomatically.
 
 David T.
>>> 
>>> IMHO it is also bad style to have:
>>> The Tutorial and Concepts Guide - an in-depth guide to the concepts.
>>> :
>>> The GnuCash Tutorial and Concepts Guide includes a comprehensive
>>> Glossary: Released or Maintainer version.
>>> 
>> 
>> We differ in our opinion here. I stand by my recommendation.
> 
> And you’re both right, it needs a more thorough rewrite to flow better. Since 
> the glossary isn’t a stand-alone document it shouldn’t have its own level-two 
> header. An additional sentence in the T paragraph under Official 
> Documentation would be better. On the other hand the wiki needs more 
> prominence, there’s a whole lot more information there than just the FAQ and 
> technical glossary.
> 
> Regards,
> John Ralls
> 
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel


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

Re: [GNC-dev] Wiki Home page

[D via gnucash-devel]

Adrien, John, Frank, and others,

Thank you all for your considered input and forbearance. In looking over the 
wiki-related threads I've generated in the last couple of days, I can clearly 
see both my petulance and pettiness on them, and I apologize.

Obviously, encouraging people to get involved is most important, and whether 
the verb used to describe this is "developing" or "improving" is not so 
important.

I apologize again for cluttering the list.

David T.

On August 18, 2018, at 7:03 AM, John Ralls  wrote:

The other application project I’m involved with, Gramps (a genealogical project 
manager) uses a wiki with restricted editing for its manual.

No, no one has ever suggested switching to a CMS for www.gnucash.org 
. I don’t think that there would be any payoff for the 
effort and it would stop us using git to manage revisions.

Regards,
John Ralls

> On Aug 18, 2018, at 4:57 AM, Adrien Monteleone 
>  wrote:
> 
> From a cursory look at other FOSS projects:
> 
> LibreOffice has an “Improve It” menu on their site, with an entry labeled 
> “Docs Team”. They utilize a wiki and printable WYSIWYG produced using LO 
> itself. (probably the lowest entry barriers of any project save for Mozilla)
> 
> GIMP has a “Participate” menu and then a link for “add Documentation” (but 
> that took me to the docs, not how to contribute. I had to go to their generic 
> developers page to find anything on contributing to the docs) It appears they 
> currently use DocBook XML/git but are looking to move to something else using 
> markdown.
> 
> Inkscape has “Contribute” “Learn” “Community” “Develop” menu entries on their 
> site. Strangely, how to help with documentation seems a bit hidden, but 
> apparently, that’s because it seems to be all via their website CMS. Details 
> info might be hidden behind their documentation mailing list they direct 
> everyone to, but I don’t see any page on what is involved in the doc process 
> itself.
> 
> Thunderbird & Firefox have a “Get Involved” link and then a simple 
> “Documentation” heading and a “Contributing to Documentation” subsection. 
> They utilize a wiki apparently exclusively. (with official help forums for 
> users instead of a mailing list which employs ’sticky’ articles people can 
> write - something I think GnuCash could benefit greatly from, especially just 
> for users.)
> 
> Gnome - has a “Get Involved” link, then a simple “Documentation” heading with 
> “Contribute to the documentation team” link. They seem to use Mallard, an XML 
> editor and Git.
> 
> Arch - yes, that Arch, uses a wiki. (integrated help is of course in the form 
> of man pages as part of their regular build system)
> 
> So perhaps taking a cue from that, a simple “Contributing to Documentation”, 
> “Help with Documentation” or a simple “Documentation” heading/link is just 
> fine. It did seem that those projects that used more complicated tools than 
> wiki/CMS hid their actual process behind several links or I had to go to the 
> developer section to find anything. I’m not suggesting GnuCash should bury 
> info however.
> 
> I see on the website, GnuCash has a simple “Writing Documentation” link and 
> the page looks pretty direct and straightforward. The Wiki page is certainly 
> more involved, but I don’t think the title “Improving” here is misleading. 
> The only thing I see missing on either page is any hint that the wiki or the 
> website are also documentation projects, or how to get involved with them, 
> and at least the former has a lower entry barrier. (Has there been any 
> discussion of moving to a CMS for the website?)
> 
> Just some thoughts...
> 
> Regards,
> Adrien
> 
> 
> 
>> On Aug 18, 2018, at 1:42 AM, David T. via gnucash-devel 
>>  wrote:
>> 
>> Frank,
>> 
>> You imply that the use of Eclipse somehow renders the documentation process 
>> simple enough for a user to identify a typo and get it fixed. I flat out 
>> disagree, and I think that using disingenuous language on the wiki home page 
>> is not going to change the reality: implementing a change in the 
>> documentation is a Process.
>> 
>> I still think the heading should be reverted to “Developing the 
>> Documentation”, and I am copying gnucash-devel as you requested.
>> 
>> David
>> 
>> 
>>> On Aug 17, 2018, at 11:23 AM, Frank H. Ellenberger 
>>>  wrote:
>>> 
>>> Hi David,
>>> 
>>> Am 16.08.2018 um 20:52 schrieb David T.:
 Frank,
 
 As you will see on gnucash-devel, I had reason to examine the wiki home 
 page today, and noticed some of the changes you have implemented there 
 over the last year or so. I wanted to discuss off list with you one of 
 those changes.
 
 You changed “Developing the Documentation” to “Improving the 
 Documentation” with the note that “developing sounds so high-flown”. I 
 think you’re wrong here, and I’d like you to change that back to 
 “Developing.” 
 
 Here’s why I think that:
 
 IF improving 

Re: [GNC-dev] Main WIki Page edit

[Adrien Monteleone]

In combination with making the T glossary sentence a part the Official 
documentation paragraph, I think the second sentence should be moved down to 
the Developer Documentation paragraph.

Also, the following line needs a number correction:

"The Documentation page on the gnucash.org website also contains ~~this~~ 
_these_ documents in”

I’d do either myself, but I see the main page is above my pay grade. (I’m sure 
for very good reason)

Regards,
Adrien

> On Aug 18, 2018, at 8:53 AM, John Ralls  wrote:
> 
> 
> 
>> On Aug 17, 2018, at 11:45 PM, David T. via gnucash-devel 
>>  wrote:
>> 
>> 
>> 
>>> On Aug 17, 2018, at 11:29 AM, Frank H. Ellenberger 
>>>  wrote:
>>> 
>>> Am 16.08.2018 um 20:37 schrieb David T. via gnucash-devel:
 Hello,
 
 I was reviewing the Wiki today to try to figure out where a page on the 
 SQL formats might get attached, and I noticed a change to the Glossary 
 section that makes for awkward English.
 
 As currently entered, the section reads:
 
 Above GnuCash Tutorial and Concepts Guide includes a comprehensive 
 Glossary: 
 [https://www.gnucash.org/docs/v2.6/C/gnucash-guide/gnc-gloss.html 
 Released] or [https://code.gnucash.org/docs/C/gnucash-guide/gnc-gloss.html 
 Maintainer] version.
 
 However, it used to say:
 
 The GnuCash Tutorial and Concepts Guide includes a comprehensive Glossary: 
 [https://www.gnucash.org/docs/v2.6/C/gnucash-guide/gnc-gloss.html 
 Released] or [https://code.gnucash.org/docs/C/gnucash-guide/gnc-gloss.html 
 Maintainer] version.
 
 I would like to ask that someone with edit permissions on the wiki home 
 page to please change the word “Above” back to “The” to make the section 
 read more idiomatically.
 
 David T.
>>> 
>>> IMHO it is also bad style to have:
>>> The Tutorial and Concepts Guide - an in-depth guide to the concepts.
>>> :
>>> The GnuCash Tutorial and Concepts Guide includes a comprehensive
>>> Glossary: Released or Maintainer version.
>>> 
>> 
>> We differ in our opinion here. I stand by my recommendation.
> 
> And you’re both right, it needs a more thorough rewrite to flow better. Since 
> the glossary isn’t a stand-alone document it shouldn’t have its own level-two 
> header. An additional sentence in the T paragraph under Official 
> Documentation would be better. On the other hand the wiki needs more 
> prominence, there’s a whole lot more information there than just the FAQ and 
> technical glossary.
> 
> Regards,
> John Ralls
> 
> ___
> gnucash-devel mailing list
> gnucash-devel@gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel


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

Re: [GNC-dev] Wiki Home page

[John Ralls]

The other application project I’m involved with, Gramps (a genealogical project 
manager) uses a wiki with restricted editing for its manual.

No, no one has ever suggested switching to a CMS for www.gnucash.org 
. I don’t think that there would be any payoff for the 
effort and it would stop us using git to manage revisions.

Regards,
John Ralls

> On Aug 18, 2018, at 4:57 AM, Adrien Monteleone 
>  wrote:
> 
> From a cursory look at other FOSS projects:
> 
> LibreOffice has an “Improve It” menu on their site, with an entry labeled 
> “Docs Team”. They utilize a wiki and printable WYSIWYG produced using LO 
> itself. (probably the lowest entry barriers of any project save for Mozilla)
> 
> GIMP has a “Participate” menu and then a link for “add Documentation” (but 
> that took me to the docs, not how to contribute. I had to go to their generic 
> developers page to find anything on contributing to the docs) It appears they 
> currently use DocBook XML/git but are looking to move to something else using 
> markdown.
> 
> Inkscape has “Contribute” “Learn” “Community” “Develop” menu entries on their 
> site. Strangely, how to help with documentation seems a bit hidden, but 
> apparently, that’s because it seems to be all via their website CMS. Details 
> info might be hidden behind their documentation mailing list they direct 
> everyone to, but I don’t see any page on what is involved in the doc process 
> itself.
> 
> Thunderbird & Firefox have a “Get Involved” link and then a simple 
> “Documentation” heading and a “Contributing to Documentation” subsection. 
> They utilize a wiki apparently exclusively. (with official help forums for 
> users instead of a mailing list which employs ’sticky’ articles people can 
> write - something I think GnuCash could benefit greatly from, especially just 
> for users.)
> 
> Gnome - has a “Get Involved” link, then a simple “Documentation” heading with 
> “Contribute to the documentation team” link. They seem to use Mallard, an XML 
> editor and Git.
> 
> Arch - yes, that Arch, uses a wiki. (integrated help is of course in the form 
> of man pages as part of their regular build system)
> 
> So perhaps taking a cue from that, a simple “Contributing to Documentation”, 
> “Help with Documentation” or a simple “Documentation” heading/link is just 
> fine. It did seem that those projects that used more complicated tools than 
> wiki/CMS hid their actual process behind several links or I had to go to the 
> developer section to find anything. I’m not suggesting GnuCash should bury 
> info however.
> 
> I see on the website, GnuCash has a simple “Writing Documentation” link and 
> the page looks pretty direct and straightforward. The Wiki page is certainly 
> more involved, but I don’t think the title “Improving” here is misleading. 
> The only thing I see missing on either page is any hint that the wiki or the 
> website are also documentation projects, or how to get involved with them, 
> and at least the former has a lower entry barrier. (Has there been any 
> discussion of moving to a CMS for the website?)
> 
> Just some thoughts...
> 
> Regards,
> Adrien
> 
> 
> 
>> On Aug 18, 2018, at 1:42 AM, David T. via gnucash-devel 
>>  wrote:
>> 
>> Frank,
>> 
>> You imply that the use of Eclipse somehow renders the documentation process 
>> simple enough for a user to identify a typo and get it fixed. I flat out 
>> disagree, and I think that using disingenuous language on the wiki home page 
>> is not going to change the reality: implementing a change in the 
>> documentation is a Process.
>> 
>> I still think the heading should be reverted to “Developing the 
>> Documentation”, and I am copying gnucash-devel as you requested.
>> 
>> David
>> 
>> 
>>> On Aug 17, 2018, at 11:23 AM, Frank H. Ellenberger 
>>>  wrote:
>>> 
>>> Hi David,
>>> 
>>> Am 16.08.2018 um 20:52 schrieb David T.:
 Frank,
 
 As you will see on gnucash-devel, I had reason to examine the wiki home 
 page today, and noticed some of the changes you have implemented there 
 over the last year or so. I wanted to discuss off list with you one of 
 those changes.
 
 You changed “Developing the Documentation” to “Improving the 
 Documentation” with the note that “developing sounds so high-flown”. I 
 think you’re wrong here, and I’d like you to change that back to 
 “Developing.” 
 
 Here’s why I think that:
 
 IF improving the documentation simply involved opening a Word file, 
 changing the text or formatting using a WYSIWIG editor, and saving the 
 result, THEN I’d agree on referring to it as “Improving the Documentation.”
 
 HOWEVER, it simply isn’t that easy—as outlined on our own wiki page. That 
 page includes guidance on: the installation of several specialized 
 software packages, the creation of accounts at github and Bugzilla, the 
 use of version control software, the editing of DocBook XML text 

Re: [GNC-dev] Main WIki Page edit

[John Ralls]

> On Aug 17, 2018, at 11:45 PM, David T. via gnucash-devel 
>  wrote:
> 
> 
> 
>> On Aug 17, 2018, at 11:29 AM, Frank H. Ellenberger 
>>  wrote:
>> 
>> Am 16.08.2018 um 20:37 schrieb David T. via gnucash-devel:
>>> Hello,
>>> 
>>> I was reviewing the Wiki today to try to figure out where a page on the SQL 
>>> formats might get attached, and I noticed a change to the Glossary section 
>>> that makes for awkward English.
>>> 
>>> As currently entered, the section reads:
>>> 
>>> Above GnuCash Tutorial and Concepts Guide includes a comprehensive 
>>> Glossary: [https://www.gnucash.org/docs/v2.6/C/gnucash-guide/gnc-gloss.html 
>>> Released] or [https://code.gnucash.org/docs/C/gnucash-guide/gnc-gloss.html 
>>> Maintainer] version.
>>> 
>>> However, it used to say:
>>> 
>>> The GnuCash Tutorial and Concepts Guide includes a comprehensive Glossary: 
>>> [https://www.gnucash.org/docs/v2.6/C/gnucash-guide/gnc-gloss.html Released] 
>>> or [https://code.gnucash.org/docs/C/gnucash-guide/gnc-gloss.html 
>>> Maintainer] version.
>>> 
>>> I would like to ask that someone with edit permissions on the wiki home 
>>> page to please change the word “Above” back to “The” to make the section 
>>> read more idiomatically.
>>> 
>>> David T.
>> 
>> IMHO it is also bad style to have:
>> The Tutorial and Concepts Guide - an in-depth guide to the concepts.
>> :
>> The GnuCash Tutorial and Concepts Guide includes a comprehensive
>> Glossary: Released or Maintainer version.
>> 
> 
> We differ in our opinion here. I stand by my recommendation.

And you’re both right, it needs a more thorough rewrite to flow better. Since 
the glossary isn’t a stand-alone document it shouldn’t have its own level-two 
header. An additional sentence in the T paragraph under Official 
Documentation would be better. On the other hand the wiki needs more 
prominence, there’s a whole lot more information there than just the FAQ and 
technical glossary.

Regards,
John Ralls

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

Re: [GNC-dev] Wiki Home page

[Adrien Monteleone]

From a cursory look at other FOSS projects:

LibreOffice has an “Improve It” menu on their site, with an entry labeled “Docs 
Team”. They utilize a wiki and printable WYSIWYG produced using LO itself. 
(probably the lowest entry barriers of any project save for Mozilla)

GIMP has a “Participate” menu and then a link for “add Documentation” (but that 
took me to the docs, not how to contribute. I had to go to their generic 
developers page to find anything on contributing to the docs) It appears they 
currently use DocBook XML/git but are looking to move to something else using 
markdown.

Inkscape has “Contribute” “Learn” “Community” “Develop” menu entries on their 
site. Strangely, how to help with documentation seems a bit hidden, but 
apparently, that’s because it seems to be all via their website CMS. Details 
info might be hidden behind their documentation mailing list they direct 
everyone to, but I don’t see any page on what is involved in the doc process 
itself.

Thunderbird & Firefox have a “Get Involved” link and then a simple 
“Documentation” heading and a “Contributing to Documentation” subsection. They 
utilize a wiki apparently exclusively. (with official help forums for users 
instead of a mailing list which employs ’sticky’ articles people can write - 
something I think GnuCash could benefit greatly from, especially just for 
users.)

Gnome - has a “Get Involved” link, then a simple “Documentation” heading with 
“Contribute to the documentation team” link. They seem to use Mallard, an XML 
editor and Git.

Arch - yes, that Arch, uses a wiki. (integrated help is of course in the form 
of man pages as part of their regular build system)

So perhaps taking a cue from that, a simple “Contributing to Documentation”, 
“Help with Documentation” or a simple “Documentation” heading/link is just 
fine. It did seem that those projects that used more complicated tools than 
wiki/CMS hid their actual process behind several links or I had to go to the 
developer section to find anything. I’m not suggesting GnuCash should bury info 
however.

I see on the website, GnuCash has a simple “Writing Documentation” link and the 
page looks pretty direct and straightforward. The Wiki page is certainly more 
involved, but I don’t think the title “Improving” here is misleading. The only 
thing I see missing on either page is any hint that the wiki or the website are 
also documentation projects, or how to get involved with them, and at least the 
former has a lower entry barrier. (Has there been any discussion of moving to a 
CMS for the website?)

Just some thoughts...

Regards,
Adrien



> On Aug 18, 2018, at 1:42 AM, David T. via gnucash-devel 
>  wrote:
> 
> Frank,
> 
> You imply that the use of Eclipse somehow renders the documentation process 
> simple enough for a user to identify a typo and get it fixed. I flat out 
> disagree, and I think that using disingenuous language on the wiki home page 
> is not going to change the reality: implementing a change in the 
> documentation is a Process.
> 
> I still think the heading should be reverted to “Developing the 
> Documentation”, and I am copying gnucash-devel as you requested.
> 
> David
> 
> 
>> On Aug 17, 2018, at 11:23 AM, Frank H. Ellenberger 
>>  wrote:
>> 
>> Hi David,
>> 
>> Am 16.08.2018 um 20:52 schrieb David T.:
>>> Frank,
>>> 
>>> As you will see on gnucash-devel, I had reason to examine the wiki home 
>>> page today, and noticed some of the changes you have implemented there over 
>>> the last year or so. I wanted to discuss off list with you one of those 
>>> changes.
>>> 
>>> You changed “Developing the Documentation” to “Improving the Documentation” 
>>> with the note that “developing sounds so high-flown”. I think you’re wrong 
>>> here, and I’d like you to change that back to “Developing.” 
>>> 
>>> Here’s why I think that:
>>> 
>>> IF improving the documentation simply involved opening a Word file, 
>>> changing the text or formatting using a WYSIWIG editor, and saving the 
>>> result, THEN I’d agree on referring to it as “Improving the Documentation.”
>>> 
>>> HOWEVER, it simply isn’t that easy—as outlined on our own wiki page. That 
>>> page includes guidance on: the installation of several specialized software 
>>> packages, the creation of accounts at github and Bugzilla, the use of 
>>> version control software, the editing of DocBook XML text files, the XSLT 
>>> validation of your edits, etc. etc. etc.
>> 
>> Using a recent Eclipse CDT bundle should have everything, which is required:
>> a Git module,
>> a Bugzilla connector,
>> a WYSIWIG XML editor,
>> a module for autotools (configuer, make, ...).
>> You could ask Geert about his success with KDevelop.
>> 
>>> Simply put, the documentation update process *IS* complicated and 
>>> “high-flown”—and to imply otherwise is misleading.
>> 
>> The idea behind the change:
>> We should not already on the main page scare off potential contributors.
>> They should decide it while reading the 

Re: [GNC-dev] Main WIki Page edit

[David T. via gnucash-devel]

> On Aug 17, 2018, at 11:29 AM, Frank H. Ellenberger 
>  wrote:
> 
> Am 16.08.2018 um 20:37 schrieb David T. via gnucash-devel:
>> Hello,
>> 
>> I was reviewing the Wiki today to try to figure out where a page on the SQL 
>> formats might get attached, and I noticed a change to the Glossary section 
>> that makes for awkward English.
>> 
>> As currently entered, the section reads:
>> 
>> Above GnuCash Tutorial and Concepts Guide includes a comprehensive Glossary: 
>> [https://www.gnucash.org/docs/v2.6/C/gnucash-guide/gnc-gloss.html Released] 
>> or [https://code.gnucash.org/docs/C/gnucash-guide/gnc-gloss.html Maintainer] 
>> version.
>> 
>> However, it used to say:
>> 
>> The GnuCash Tutorial and Concepts Guide includes a comprehensive Glossary: 
>> [https://www.gnucash.org/docs/v2.6/C/gnucash-guide/gnc-gloss.html Released] 
>> or [https://code.gnucash.org/docs/C/gnucash-guide/gnc-gloss.html Maintainer] 
>> version.
>> 
>> I would like to ask that someone with edit permissions on the wiki home page 
>> to please change the word “Above” back to “The” to make the section read 
>> more idiomatically.
>> 
>> David T.
> 
> IMHO it is also bad style to have:
> The Tutorial and Concepts Guide - an in-depth guide to the concepts.
> :
> The GnuCash Tutorial and Concepts Guide includes a comprehensive
> Glossary: Released or Maintainer version.
> 

We differ in our opinion here. I stand by my recommendation.

David

> ~Frank
> 

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

Re: [GNC-dev] Wiki Home page

[David T. via gnucash-devel]

Frank,

You imply that the use of Eclipse somehow renders the documentation process 
simple enough for a user to identify a typo and get it fixed. I flat out 
disagree, and I think that using disingenuous language on the wiki home page is 
not going to change the reality: implementing a change in the documentation is 
a Process.

I still think the heading should be reverted to “Developing the Documentation”, 
and I am copying gnucash-devel as you requested.

David


> On Aug 17, 2018, at 11:23 AM, Frank H. Ellenberger 
>  wrote:
> 
> Hi David,
> 
> Am 16.08.2018 um 20:52 schrieb David T.:
>> Frank,
>> 
>> As you will see on gnucash-devel, I had reason to examine the wiki home page 
>> today, and noticed some of the changes you have implemented there over the 
>> last year or so. I wanted to discuss off list with you one of those changes.
>> 
>> You changed “Developing the Documentation” to “Improving the Documentation” 
>> with the note that “developing sounds so high-flown”. I think you’re wrong 
>> here, and I’d like you to change that back to “Developing.” 
>> 
>> Here’s why I think that:
>> 
>> IF improving the documentation simply involved opening a Word file, changing 
>> the text or formatting using a WYSIWIG editor, and saving the result, THEN 
>> I’d agree on referring to it as “Improving the Documentation.”
>> 
>> HOWEVER, it simply isn’t that easy—as outlined on our own wiki page. That 
>> page includes guidance on: the installation of several specialized software 
>> packages, the creation of accounts at github and Bugzilla, the use of 
>> version control software, the editing of DocBook XML text files, the XSLT 
>> validation of your edits, etc. etc. etc.
> 
> Using a recent Eclipse CDT bundle should have everything, which is required:
> a Git module,
> a Bugzilla connector,
> a WYSIWIG XML editor,
> a module for autotools (configuer, make, ...).
> You could ask Geert about his success with KDevelop.
> 
>> Simply put, the documentation update process *IS* complicated and 
>> “high-flown”—and to imply otherwise is misleading.
> 
> The idea behind the change:
> We should not already on the main page scare off potential contributors.
> They should decide it while reading the respective pages.
> 
> And it should also address "Hey, I found a typo."
> 
>> Please revert the heading to “Developing the Documentation.”
> 
> If you still think, it should be reverted, address it to gnucash-devel.
> 
>> Thanks,
>> David
>> 
> Regards
> Frank
> 

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