On Jun 4, 2007, at 2:58 AM, Antony Dovgal wrote:
Those on the internals list will recognize me; for those who
don't, I'm Gwynne, and I've volunteered to fully document the Zend
Engine 2 API from a developer perspective. Attached to this
message is the first set of patches for the new documentation.
Nice work!
Thanks :).
I've created a completely new part of the manual to cover the
large topic
I'm not sure it's a good idea.
I'd prefer improving/changing the existing part of the manual
instead of introducing a new one.
Do you think it's possible?
In total honesty, no, I don't. While the existing docs have served
for some time, it's my opinion that they were never very well
structured, and that users will benefit much more from a complete
rewrite than from an attempt to update what's there. Philip and I
have been discussing various strategies for working in the new
material, but we haven't come up with anything that seems fully
suitable so far. Some of the ideas on the table are:
The original docs structure - Completely replace the internals.*
section with the new material and move the old stuff to an appendix
or out of the manual. I personally disagree with this option, as PHP
4 is still in relatively wide use and my intention is to comment on
ZE1 minimally at best in the new material.
The structure I originally proposed - Leave the internals.* section
in for reference, create an internals2.* section for the new
material. As you and Philip have obviously noticed, this is a bit
confusing from an outsider's perspective.
Put each ZE version under its own subsection - internals.* would
become internals.ze1.*, internals.ze2.*, internals.ze3.*. This has a
few drawbacks, such as the necessary movement of files in CVS and the
fact that, with any luck, the ZE3 docs will be able to evolve more
naturally from the ZE2 docs. One alternate to this idea is to do just
ze1 and ze2 in this manner and let ZE3 speak for itself as things
develop.
Place the ZE2 material as a subsection of internals.* - I don't like
this idea at all; it hides the new documentation inside a structure
that's already confusing and misleading in my opinion.
A completely separate internals developer manual - This would become
a completely new project, and Philip and I agree that the best way to
handle it if it happens would be to put at least some ZE2 material in
the existing manual and focus on ZE3 as much as possible in the new
one. Things like how to set up the build system and where to put the
new docs would be issues to consider. This is more of a separate idea
than an alternative structure suggestion, since it would require at
least some work in the original manual, and I'd like to put it up for
more general discussion.
If you have any other ideas, fire away :).
-- Gwynne, Daughter of the Code
"This whole world is an asylum for the incurable."
