Cheers,
And now, here we start again! :) Following on the creation of the doc-license mailing list, we are ready to start moving on with crediting. For those not aware of why this was a needed step, here is the explanation:
Since the copyright statement said that the PHP Documentation Group members are those people listed as authors, they were the copyright holders. Legally they were entitled to make decisions about licensing. So if we would have been adding more people to the list, more people would have been asked for one decision, and the licensing questions would never got answered.
On the 2003 docmeeting and in other discussions, it turned out that it would not be ideal to elect people to decide on licensing, since that would lead to possible wars and confusion. Therefore it was decided that the licesing questions will be kept open, and anyone interested can join in the discussions and decisions. This is why the doc-license list was created. Now the licensing decisions are delegated to the members of that list (which is openly archived to be fair), so we can add more authors without risking complication of the licensing decisions.
I have quoted the 2003 findings below. What I see now is that the per-section author information embedded in DocBook XML is for the future, since we have a lot more important tasks to do then researching authors now (most of the reference section was cvs added by Hatmut as part of the file split, some of the files have been moved by myself, and we should not be credited as authors of all those files, so a lot of research would be needed to get correct author lists for the files).
What we can do now is to build up a fairly correct list of authors to credit, and then receive complaints from those who have not get in for some reason, and are certain they should be there. That list can be compiled from CVS history. As far as I see we would need an active authors list and a historical author list, actives being those having cvs commits in the past half year or so. This would encourage people to be more active hopefully. We also need a list of note maintainers for these two sections. The question is if it would be possible to generate these lists as bases for discussion from available history (notes mailing list archives, phpdoc cvs history), so we can see how many people are in those lists, and we can start discussion on how those would be presented ideally.
Here are the 2003 meeting findings related to crediting. I don't think we should make everything working first time (ie. postpone crediting PHP extension authors a bit). IMHO the most important is to list people historically active in the manual (and even not listed in the current list) and list currently active people prominently (especially including note editors, since they are not that much appreciated currently).
------------------------------------------------------------8<-------------
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.
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.
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 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.
------------------------------------------------------------8<-------------
Opinions, comments, ideas?
Goba
