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
