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