On Jan 27, 2007, at 8:26 AM, Mehdi Achour wrote:
Hello internals,
I've been helping with PHP documentation for 4 years now, and I
still can't help the fact that a loooot of things are not
documented, that our/my way of handling the PHP documentation
update is not accurate, nor productive, nor bug free at all.
I think it's been ~7 years of off and on work for me... same as it
ever was. I do think it's *much* more productive and accurate than it
was 7 years ago, though. Not quite bug-free, yet.
(You think it's bad now...)
Personally, I try to follow commits on php.cvs, bug reports, Change
Log?, user notes on the online manual.. but I still have the
feeling of missing a lot of changes. After a year away from the
project, I have _no_ clue what was added, when, and whether it was
added to our documentation or not.
You are in the same boat as me..... The dunes change, but the sands
are always shifting. I might have been away for n years. Much has
changed, and much has not.
I know that you developers are willing to help a lot with it, but
that you cannot manage to save the spare time needed to do it the
right way. That's why I would like to propose a simple/small/
timeless change in your CVS commit messages: If you feel that the
change need to be documented, place the @doc keyword at the end of
your message log entry.
Scenario one:
All behavior changes must be documented, this tag is always there,
and thus not useful.
Scenario two:
Developers decide when changes are "important" enough to be
documented, and tag as such, in which case we go back to...
Scenario three:
The problem of developers who don't think documentation is needed for
their changes.
In the end, I often wonder if this is documentation issue, or a
developer issue. Developers read the code, and often don't need *any*
documentation. Our end users read a manual page, and wonder what a
"bool" or "int" is, as a very large number of our users are fairly
new to the whole subject matter.
(side joke, does PHP have a zool(), destroyer of all world (global)
variables?)
Anyways, to me, the real challenge of working on the PHP docs is not
getting programmers to feed us reliable, consistent, data all the
time (they won't), but rather, helping out our end users who don't
read source code.
Vanity devs will want us to document everything, quiet devs will
never tag it.
In the end, the doc team still has to fix it.
-Ronabop
