PHP Documentation - Re: [PHP-DOC] crediting authors and contributors

Author

Re: [PHP-DOC] crediting authors and contributors

Vincent Gevers

2004-06-09, 3:56 pm

On Wednesday 09 June 2004 12:31, Gabor Hojtsy wrote:
>
> Types of other contributors:
> - user note maintainers:
> andrew, meebay, didou, ... The list can be generated from
> the php-notes mailing list archive. Wez is going to do make
> a script pull it out from archives, and after that we're going
> to put up guidelines for who is a maintainer and who is not.

there is an unofficial maintainers list
http://paste.uni.cc/notes/index.php

if needed, I can put the source online

- Vincent

Gabor Hojtsy

2004-06-09, 3:56 pm

>>Types of other contributors:
>
> there is an unofficial maintainers list
> http://paste.uni.cc/notes/index.php
>
> if needed, I can put the source online

Would be nice to have it collected in phpdoc/scripts. The 'w

stat'
seems to be an all time stat BTW. Would be nice to extend in a way I
suggested, if it seems to be fine with you: List people who maintained
notes in the past half year and those who maintained notes before it.
Then chop both lists at some human define place. Currently 100 actions
seems to be a good chop point for me on the all time list - which would
include around 30 editors minus the ones listed in the active list.

Goba

Nuno Lopes

2004-06-09, 3:56 pm

> Wez came up with the idea of putting author information into the
> refentries and sections, which should make it quite easy to give credit.
> This can be done with a <docinfo> in a <refentry>, and a <sectioninfo>
> for a <section>. Both of these take on an <authorgroup> element which
> may contain all necessary information. This method lets people decide on
> who to give credit to on a small scale, and enables automation of
> extracting credit information from XML files.
>
> Start from http://www.docbook.org/tdg/en/html/authorgroup.html to get
> more information on the tag and possible parents.
>
> For translated versions, the nicknames can be fetched from the Revision
> comments, where those are appropriately specified. For the original
> English text, everything not added by Hartmut [who have done file
> splits, movearounds] can probably be credited to the first committer.
>
> For the other files, people should just complain that they added it, and
> it can be done by hand (they provide a link to their commit). For the
> language, tutorial, and other sections it can be done by hand for now.

I don't know if this is a good idea... Having a tag in every file?
And what names would be listed? The original writer of the file? The guy who
added some examples? The guy who fixed some bugs on that file?
Isn't easy! I would vote to have all names together somewhere in the
documentation (frontpage, appendix,....).

> There are other type of contributors, who we cannot assign to individual
> XML files. So there should be a separate [maybe partially generated]
> credits file with their details.
>
> Types of other contributors:
> - user note maintainers:
> andrew, meebay, didou, ... The list can be generated from
> the php-notes mailing list archive. Wez is going to do make
> a script pull it out from archives, and after that we're going
> to put up guidelines for who is a maintainer and who is not.
> - techinical editors:
> hartmut, egon, goba ... Techical editors [unless someone
> finds a better name] are those who edit the documentation
> and contribute to the build system helping the work of
> authors and translators.
> - authors:
> stig, philip ... Authors are for one part those who are
> historically preserved, and are not available to connect
> to XML files as authors. For another part, they are those
> who contribute content on a large scale.
>
> It is generally quite hard to put people in a group, thus it will be
> decided by group consensus. A person is not limited to be listed in only
> one group.

Agree here

> The author information detailed above is used to print out the author's
> name on individual documentation pages in the footer with a small font.
> If there is no author info section for a specific page in the XML file,
> then the author[s] of the parent is shown.
>
> The author info will also be used to generate a full listing of every
> contributor involved in the documentation process. This list will be
> presented on the bookinfo page. For translations, the translators names
> will show below the authors in a separate section.
>
> History should be preserved/maintained in all the crediting systems
> involved.

The idea here was to use livedocs to display the author along with the file
revision AFAIK. As I stated before, I think isn't really need to have so
much credit.

> The idea of presenting the author of the PHP extension itself also came
> up, and was generally agreed on. The documentation system can grab the
> list of authors from the php-src/EXTENSIONS file, and will generate
> extension specific author information by the side of the documentation
> authors' list.

Yes, we may add the authors... And what about update the names in phpinfo()?
:-)

Nuno

Gabor Hojtsy

2004-06-09, 3:56 pm

>>Start from http://www.docbook.org/tdg/en/html/authorgroup.html to get
>
> I don't know if this is a good idea... Having a tag in every file?
> And what names would be listed? The original writer of the file? The guy who
> added some examples? The guy who fixed some bugs on that file?

All guys who provided significant value in the contents of that section.

> Isn't easy! I would vote to have all names together somewhere in the
> documentation (frontpage, appendix,....).

It's not easy to do all at one time but it would be a good method in the
future to add docs this way and update older docs with author info as
time permits. PEAR people generate their author list somehow similarly
if I understand correctly.

>
> The idea here was to use livedocs to display the author along with the file
> revision AFAIK. As I stated before, I think isn't really need to have so
> much credit.

It is easier to give credit on a fine grained scale, since then even
people providing relatively small amount of additions will get listed.

>
> Yes, we may add the authors... And what about update the names in phpinfo()?
> :-)

It is not possible to list all authors and contributors in the phpinfo()
output - also including all note maintainers. So once we see the list we
would like to include here, we need to decide on a method to choose the
list of people who are going to go to the phpinfo() page (and a 'more'
link should be there :)

Goba

Gabor Hojtsy

2004-06-27, 3:55 pm

>>>Would be nice to have it collected in phpdoc/scripts. The 'w

stat'
>
> I've done my homework and I think something like this is what you are looking for:
> http://notes.allowee.no-ip.com/output.php
>
> comments welcome :)
>
> I'm thinking about the name notes_stats.php for in phpdoc/scripts, is that ok?
>
> maybe this can also be used for the new documentation website..

Yep, notes_stats.php would be a fine name...

So as I have suggested, I still think that we should have two lists of
note maintainers in the documentation. The first is the current active
maintainers (names from the past year with at least 100 actions), the
second is the past active maintainers (others who have more than 100
actions, but before the half year mark). Of course this half year mark
will be moving, so continually active people will be better positioned,
but significant past contributions will still be honored. The action
limit of 100 instead of a 'top n names' approach IMHO guarantees that
people will get credited for their past work, even if they have
contributed a long time ago (they will not get under the mark).

The list of current active note maintainers is quite good looking to
include in phpinfo() IMHO.

Note that this is a suggestion, but if noone objects against it, then it
will become a rule (which is one that is changeable in the future BTW
:). So speak up if you see you are not credited but you should be, or
you are not credited enough :)

Goba

Sponsored Links