<snip>
The removed text in those PDO docs did not follow the guidelines so
it was a bug.
What guidelines? There are guidelines in the PHP Documentation HOWTO
for documenting user space interfaces. I haven't found any guidelines
for what appears in the Appendices in the PHP Manual (which are a
completely different kind of documentation). Please point out where
these guidelines exist -- I can't accept your justification,
otherwise.
The appendix is part of the manual just the same as it's all one big
manual. Although the internals documentation is not in the appendix,
a lot of stuff is that is critical to other parts of the manual. If
something is not explicitly stated then common and accepted behavior
here also comes into play. The documentation in question was
implemented different from any other and is wrong.
In many projects, the equivalent of what appears in the PHP Manual
Appendices gets broken out into separate documents - and these
separate documents get separate author (and other role) credits.
Perhaps in your role as the PHP Manual editor, you could lead the
php-doc community to revisit the decision to aggregate all PHP-related
documentation together into a single package. And create guidelines
for the documentation other than the user-facing syntax, functions,
and methods.
That's one idea and in some communities it might be necessary but I
prefer helping people work together by creating and owning the entire
manual as a single unit. And while doing so allow an open path to any
part of the documentation with no sense of ownership to files or
pieces of text. We are working up plans to ease contribution access
to the documentation and once the tools are in place it will be even
easier for the community to contribute to the entire manual.
Attributing credits exists currently but ideas to enhance this
procedure are being worked on as well. Methods such as promoting the
CVS (SVN?) history. I understand this team approach can be difficult
considering the increased number of different ways to promote a
topic, ways like blogs, conference talks, books, magazines, sponsored
sites, personal sites, etc. but still do believe it is possible to
maintain. I'm against the "when do I add my name to a file?" approach
but do feel the current credits list is too small and in need of
help. So needless to say I am very much against the hodgepodge
approach of aggregating documentation from outside sources unless
said sources want to contribute the documentation like the other
hundreds or so contributors do currently.
Regards,
Philip
