Uniform policy for author credits in contrib module documentation?

As of CVS HEAD, some of the contrib module documentation pages have
extensive credit screeds, eg
http://developer.postgresql.org/pgdocs/postgres/cube.html
and some just have the author's name, with or without an <email> link,
and some don't have anything at all.

This bothers me; it seems like we should have a more uniform approach.

There are some arguments to be made for not having credits at all.
We don't make a habit of crediting individuals anywhere else in the SGML
docs; credits in the source code and/or CVS logs are supposed to be
enough. And we do still have author credits in contrib/README, not to
mention the individual source code files. And there's the whole issue
that files that have been there awhile have probably been tweaked by
a number of people besides the original author. OTOH I dislike removing
credits that the authors might have expected to be there, and the
contrib modules mostly do have identifiable original authors.

If we do want to keep credits in the SGML pages, how extensive should
they be? I already took it on myself to remove Gene Selkov's snailmail
address, but do we even want email addresses there? A lot of them are
probably dead, and the ones that aren't are causing their owners to get
extra spam, because an <email> link is about the easiest thing to scrape
from a webpage that there could possibly be.

I don't have a strong opinion one way or the other, except that I think
we should have a uniform policy for all the contrib modules.

Comments?

regards, tom lane

Tom Lane wrote:
> As of CVS HEAD, some of the contrib module documentation pages have
> extensive credit screeds, eg
> http://developer.postgresql.org/pgdocs/postgres/cube.html
> and some just have the author's name, with or without an <email> link,
> and some don't have anything at all.
>
> This bothers me; it seems like we should have a more uniform approach.

[snip]

> I don't have a strong opinion one way or the other, except that I think
> we should have a uniform policy for all the contrib modules.
>
> Comments?

As far as I'm concerned, you can remove any credits for me from the
contrib modules I've worked on (or I can do it if you'd prefer).

In any case +1 for a uniform policy, and +1 for removing credits from
documentation.

Joe

Tom Lane wrote:
> As of CVS HEAD, some of the contrib module documentation pages have
> extensive credit screeds, eg
> http://developer.postgresql.org/pgdocs/postgres/cube.html
> and some just have the author's name, with or without an <email> link,
> and some don't have anything at all.

> I don't have a strong opinion one way or the other, except that I think
> we should have a uniform policy for all the contrib modules.

Well once we push directly into the core documentation I agree that
outside of release notes (although you just brought that up in another
thread) we don't need to be mentioning contributions like that. Those
who have contributed are in the logs.

Further those who have provided reasonable contribution really should be
mentioned on the contributors page that is up for discussion which would
make the rest of this moot yes?

Sincerely,

Joshua D. Drake

>
> Comments?
>
> regards, tom lane
>
> ---------------------------(end of broadcast)---------------------------
> TIP 2: Don't 'kill -9' the postmaster
>

"Joshua D. Drake" <jd(at)commandprompt(dot)com> writes:
> ...Further those who have provided reasonable contribution really should be
> mentioned on the contributors page that is up for discussion which would
> make the rest of this moot yes?

I don't have any objection to listing people on the contributors page
on the strength of their work on contrib modules. But that seems
orthogonal to the question of what should be in the SGML docs ...

regards, tom lane

Tom Lane wrote:
> "Joshua D. Drake" <jd(at)commandprompt(dot)com> writes:
>> ...Further those who have provided reasonable contribution really should be
>> mentioned on the contributors page that is up for discussion which would
>> make the rest of this moot yes?
>
> I don't have any objection to listing people on the contributors page
> on the strength of their work on contrib modules. But that seems
> orthogonal to the question of what should be in the SGML docs ...

All I was saying is I don't think we need the redundancy :). E.g; if
they are worthy in the docs, they are worthy on the contributors page
and thus not needed in the docs.

I am not of a strong opinion either way but it seems having names
plastered everywhere just creates more management of information for no
particular purpose.

Sincerely,

Joshua D. Drake

>
> regards, tom lane
>

On Wed, Dec 05, 2007 at 10:46:51PM -0800, Joshua D. Drake wrote:
> Tom Lane wrote:
> >As of CVS HEAD, some of the contrib module documentation pages have
> >extensive credit screeds, eg
> >http://developer.postgresql.org/pgdocs/postgres/cube.html
> >and some just have the author's name, with or without an <email> link,
> >and some don't have anything at all.
>
> >I don't have a strong opinion one way or the other, except that I think
> >we should have a uniform policy for all the contrib modules.
>
> Well once we push directly into the core documentation I agree that
> outside of release notes (although you just brought that up in another
> thread) we don't need to be mentioning contributions like that. Those
> who have contributed are in the logs.
>
> Further those who have provided reasonable contribution really should be
> mentioned on the contributors page that is up for discussion which would
> make the rest of this moot yes?

+1, since they are listed in the release notes when the contrib modules are
added - just like any other piece of code. IMO no reason to treat contrib
differently from any other code in this case.

//Magnus

On Dec 5, 2007 8:58 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> If we do want to keep credits in the SGML pages, how extensive should
> they be?

...

> I don't have a strong opinion one way or the other, except that I think
> we should have a uniform policy for all the contrib modules.

One of the things that I used to do with the old HOWTO documentation
from the Linux Documentation Project was jump directly to the
Acknowledgement or Credit sections and read who the author had decided
to thank, and then search for more information about those people and
what they had done.

While it might be a pain to maintain that information, it does
humanize and provide context for a document.

Also, the tradition of thanking people (or higher powers) and taking a
few moments to reflect on who might have helped one accomplish
something is a good one. Maybe I'm just being nostalgic, but I like
that the content of credit sections is not uniform.

Rather than remove credits, we could apply a regex to obfuscate the
email addresses, and offer a mention to authors in the more general
contributors area when packages are added.

-selena

--
Selena Deckelmann
PDXPUG - Portland PostgreSQL Users Group
http://pugs.postgresql.org/pdx
http://www.chesnok.com/daily

Tom,

> If we do want to keep credits in the SGML pages, how extensive should
> they be? I already took it on myself to remove Gene Selkov's snailmail
> address, but do we even want email addresses there? A lot of them are
> probably dead, and the ones that aren't are causing their owners to get
> extra spam, because an <email> link is about the easiest thing to scrape
> from a webpage that there could possibly be.

Historically, the only way to troubleshoot some of the contrib modules
was to e-mail the author. If people think that we've reached a standard
that everything in /contrib is now well-documented and supported by the
general community, the I suppose we don't need contact information. I'm
not so sure myself.

--Josh

Josh Berkus <josh(at)agliodbs(dot)com> writes:
> Historically, the only way to troubleshoot some of the contrib modules
> was to e-mail the author. If people think that we've reached a standard
> that everything in /contrib is now well-documented and supported by the
> general community, the I suppose we don't need contact information. I'm
> not so sure myself.

I do not think that we should encourage people to mail the authors first
rather than pgsql-bugs. For one thing, a lot of those addresses are
dead, and some of the ones that aren't don't respond especially fast.

If the community-at-large can't handle a bug, we certainly have enough
institutional memory to try to contact the original author, even if that
address isn't in the SGML docs.

regards, tom lane

Tom Lane wrote:
> Josh Berkus <josh(at)agliodbs(dot)com> writes:
>> Historically, the only way to troubleshoot some of the contrib modules
>> was to e-mail the author. If people think that we've reached a standard
>> that everything in /contrib is now well-documented and supported by the
>> general community, the I suppose we don't need contact information. I'm
>> not so sure myself.
>
> I do not think that we should encourage people to mail the authors first
> rather than pgsql-bugs. For one thing, a lot of those addresses are
> dead, and some of the ones that aren't don't respond especially fast.
>
> If the community-at-large can't handle a bug, we certainly have enough
> institutional memory to try to contact the original author, even if that
> address isn't in the SGML docs.
>

Perhaps the at a minimum the email goes in the commit?

Joshua D. Drake

> regards, tom lane
>
> ---------------------------(end of broadcast)---------------------------
> TIP 5: don't forget to increase your free space map settings
>

Joshua D. Drake wrote:
> Tom Lane wrote:
>> Josh Berkus <josh(at)agliodbs(dot)com> writes:
>>> Historically, the only way to troubleshoot some of the contrib
>>> modules was to e-mail the author. If people think that we've
>>> reached a standard that everything in /contrib is now
>>> well-documented and supported by the general community, the I
>>> suppose we don't need contact information. I'm not so sure myself.
>>
>> I do not think that we should encourage people to mail the authors first
>> rather than pgsql-bugs. For one thing, a lot of those addresses are
>> dead, and some of the ones that aren't don't respond especially fast.
>>
>> If the community-at-large can't handle a bug, we certainly have enough
>> institutional memory to try to contact the original author, even if that
>> address isn't in the SGML docs.
>>
>
> Perhaps the at a minimum the email goes in the commit?
>

I don't see any reason, unless we're going to start doing that for all
contributions. 'contrib' is a serious misnomer anyway, and there's no
reason to think in general that the original author is specially
responsible for any of it. I think Tom's point is entirely valid.

cheers

andrew

On Dec 7, 2007 9:03 AM, Andrew Dunstan <andrew(at)dunslane(dot)net> wrote:
>
>
> Joshua D. Drake wrote:
> > Tom Lane wrote:
> >> Josh Berkus <josh(at)agliodbs(dot)com> writes:
> >>> Historically, the only way to troubleshoot some of the contrib
> >>> modules was to e-mail the author. If people think that we've
> >>> reached a standard that everything in /contrib is now
> >>> well-documented and supported by the general community, the I
> >>> suppose we don't need contact information. I'm not so sure myself.
> >>
> >> I do not think that we should encourage people to mail the authors first
> >> rather than pgsql-bugs. For one thing, a lot of those addresses are
> >> dead, and some of the ones that aren't don't respond especially fast.
> >>
> >> If the community-at-large can't handle a bug, we certainly have enough
> >> institutional memory to try to contact the original author, even if that
> >> address isn't in the SGML docs.
> >>
> >
> > Perhaps the at a minimum the email goes in the commit?
> >
>
> I don't see any reason, unless we're going to start doing that for all
> contributions. 'contrib' is a serious misnomer anyway, and there's no
> reason to think in general that the original author is specially
> responsible for any of it. I think Tom's point is entirely valid.

I think it is totally appropriate to replace the email address contact
information with a link to pgsql-bugs.

But there are reasons other than bugfixing to contact the original
author of a patch or contrib packages. Some of those could include:

* collaboration on a professional, hobby or academic research level
* journalism/books written about PostgreSQL
* academic or historical research into the development of PostgreSQL
* job prospects
* socializing

For those reasons, I think it would be a huge loss to the community to
remove the credit sections or to prevent their inclusion in future
documentation. Maintaining them leaves a breadcrumb trail that
otherwise would be lost in mailing list threads and commit logs that
are very difficult for a person without specialized knowledge to
navigate. Why make contacting people hard?

Some of the contrib features are likely targets for future research
and development (for example: tsearch, HOT, pl/lolcode - not contrib,
but awesome!) and in that context, the specific people involved are
important.

Contrib documentation will get folded into the main docs eventually
(and at that point, the credits are removed). But the record of that
evolution is easily accessed, without any special knowledge of a
revision control system, or mailing list culture.

And I realize that the logical extension of what I am saying is a
research and documentation project about the people who all have
contributed to the development of PostgreSQL.

-selena

--
Selena Deckelmann
PDXPUG - Portland PostgreSQL Users Group
http://pugs.postgresql.org/pdx
http://www.chesnok.com/daily

On Thursday 06 December 2007 03:54, Magnus Hagander wrote:
> On Wed, Dec 05, 2007 at 10:46:51PM -0800, Joshua D. Drake wrote:
> > Tom Lane wrote:
> > >As of CVS HEAD, some of the contrib module documentation pages have
> > >extensive credit screeds, eg
> > >http://developer.postgresql.org/pgdocs/postgres/cube.html
> > >and some just have the author's name, with or without an <email> link,
> > >and some don't have anything at all.
> > >
> > >I don't have a strong opinion one way or the other, except that I think
> > >we should have a uniform policy for all the contrib modules.
> >
> > Well once we push directly into the core documentation I agree that
> > outside of release notes (although you just brought that up in another
> > thread) we don't need to be mentioning contributions like that. Those
> > who have contributed are in the logs.
> >
> > Further those who have provided reasonable contribution really should be
> > mentioned on the contributors page that is up for discussion which would
> > make the rest of this moot yes?
>
> +1, since they are listed in the release notes when the contrib modules are
> added - just like any other piece of code. IMO no reason to treat contrib
> differently from any other code in this case.
>

Hmm, I have often seen that the person listed in the contrib docs was
considered the person to contact if you had questions/comments/patches/etc...
about a specific contrib module. I wonder if people would still get the same
level of help if those names are removed and they have to go to the regular
mailing lists for help (which contrib authors may not follow).

--
Robert Treat
Build A Brighter LAMP :: Linux Apache {middleware} PostgreSQL