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 <jra...@ceridwen.us> 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 <http://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 > <adrien.montele...@lusfiber.net> 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 >> <gnucash-devel@gnucash.org> 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 >>> <frank.h.ellenber...@gmail.com> 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 >>> <pEpkey.asc> >> >> _______________________________________________ >> 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 _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
