Ahoy Hannes!
.oO( Yes, go, make the PHP manual better! )
Am 01.02.2012 11:45, schrieb Hannes Magnusson:
We already do some parts of the work in the form of changelogs on each
function page, introducing this new page could aggregate that and
provide more comprehensive information in the form of examples and
longer human readable text.
Exactly: comprehensive overview, pit falls, eventually brief examples...
For example, I have tried to explain the main motto/theme/idea for a
version of my PECL extensions. Users may look at it, find that it is
only a maintenance release and skip in order not to touch their running
system. Or, users may jump on it because of a new super-duper feature
they desire.
If we could do this for built-in exts first, and if it works out
expand it to the rest of the pecl extensions.
.oO( Sure, but don't count on me, thus no "vote" from the lurker ;-) )
I think this will solve the docrot of the migration guides, as they
almost never get updated with new info after the .0 releases, which
gives the users the wrong impression of changes.
And needing to navigate through every single damn function in the
manual to see what has changed is very very annoying.
Well, it cures the problem somewhat by:
- creating central, comprehensive overviews
- increasing pressure to update NEWS as it makes your
work visible to all users
A changelog is for sure better suited for finding migration hints than
scanning every manual page.
Though, it may still not be comparable to a migration guide. A migration
guide may have an even coarser granularity. For example, the changelog
of a PECL extension may describe how to get from 1.1 -> 1.2, 1.2 -> 1.3,
... 1.9 -> 2.0 but a migration guide may also describe the direct path
from 1.0 -> 2.0.
With core extensions, which are bound to PHP major releases, this may
not be an issue. For PECL extensions, which are mostly free to choose
their version numbers as I understand it, it may be.
Whatever, if the PHP docs team can cope with the extra work, please go
for the changelogs in the manual. I found to spend most time not for
adding a changelog entry but for describing the change, incorporating it
into the main sections and reasonable cross linking from the changelog
to the main sections.
Ulf
