Recommended Change to Author LIsting in Documentation
jralls at ceridwen.us
Tue Dec 13 19:37:54 EST 2016
> On Dec 10, 2016, at 10:49 AM, David T. via gnucash-devel <gnucash-devel at gnucash.org> wrote:
> In response to seeing yet another new user sending a support request directly to one of the people mentioned in the documentation, I created Bug 775919 (https://bugzilla.gnome.org/show_bug.cgi?id=775919 <https://bugzilla.gnome.org/show_bug.cgi?id=775919>) as a proposed change to the way that the docs present the author attributions. In that bug, I state:
> I recommend the following:
> 1) Remove all individual names and email addresses from the documentation title page, and replace them with a general attribution to "The GnuCash Documentation Team." Since the current copyright is to this entity, I think this is not only convenient, but also more accurate than the current list.
> 2) Place a large note on the title page identifying gnucash-users as the proper location to which to direct help requests. Section 2.4.2 is clearly not prominent enough for new users.
> 3) Retain the list of contributors that show on the title page verso. I will note that this list omits email addresses. In addition, add a note there about who and what the GnuCash Documentation Team is.
> I propose: "The GnuCash Documentation Team is a self-designated group of GnuCash users and developers who have volunteered to write this documentation for the benefit of the broader user base. People who are interested in joining this group are encouraged to express their interest on the GnuCash lists (gnucash-users and gnucash-devel) for further direction.”
> John Ralls thought that this change should be run past the Devel list, and so here I am, giving it a run. As one of the named contributors, I personally would prefer that my email not be included in the documentation, but I defer to the general interest of the group.
I couldn't get anything beyond the author on either side of the title page, so I've reduced the author list to "The GnuCash Documentation Team" and added a preface block titled "About the Author" with David's proposed paragraph and then "Contributors to the team so far have been:" followed by a list of authors and translators for the document in question.
Note to Frank, Mechtilde, and Pedro: I did this in English on the German and Portuguese translations. If you can get this translated by Saturday for the release that would be great. I'd rather not use Google Translate.
I've also cleaned up the "More Help" section and applied it to the Guide as well as the Help. It's at the end of the first chapter (Overview) in the Guide and the second (Using this Document and Getting Help) in Help. Would it be better to make it preface material to make it more prominent?
The changes should show up in tomorrow's docs nightlies, http://code.gnucash.org/docs/. The "C" directory has the English version. I didn't copy the updated "More Help" into the German or Portuguese translations; Italian is generated so it will be there too, but in English.
More information about the gnucash-devel