On Jul 1, 2009, at 9:37 PM, Eddie Drapkin wrote:

Hey there!

I'm (slowly *shakes fist*) working on reworking the Reflection
documentation to be more friendly, organized, etc. etc. and more
closely resemble any of the other multitude of multi-class pacakges.
Long story short, I'm workign right now on the Introduction, and what
can go there? I've basically limited what I'd like to put there into
several sections:

1) An introduction to reflection in general terms, similar to what
already exists, but more elaborate
2) A brief decription of the general usage in PHP
3) "Why use Reflection?" - an analysis of realistic cases where
Reflection is useful, perhaps linking ot external resources for
further research (wikipedia, probably)

And basically, I've not seen (not that it doesn't exist), an example
of #3 in use in the PHP manual any where, nor can I find any sort of
RFC or guideline forbidding it.  So, my question is whether or not
that sort of documentation is allowed or not.

As I was learning PHP, I came across documentation for extensions that
seemed useless or silly to me, at the time and often went off into
research tangents trying to figure out why Tidy exists (really D=) or
what the viable use cases for memcached were or why opcode caches
exist, etc. etc. All in all, it did me a lot of good as a web
developer to do that research, but I think someone a lot less diligent
or insane would have read the synopsis, though "man, fuck this, it's
useless" and moved on, without expanding their horizons in PHP because
of no immediate need, which is A Damn Shame (pardon the french, all
around).  I think that if it's allowed, sections like "What's it for?"
whether as their own "page" or just a paragraph in the introduction,
even if they're short, can't possibly be a bad thing for a budding
developer.  But then again, it could also be seen as documentation
cruft and not absolutely necessary.

What are your thoughts?  How should I continue?

I recently began the process of moving Reflection from the OOP5 section to reference/reflection so there is that. It's a daunting task so maybe in a week or so it'll be complete. I'm not adding much new information so there will be a lot ready for improvement so please think about it and get ready to add the real documentation. Imagine each class/method having its own page.

Although the manual is fairly structured it's open for new ideas especially since it moved to the book per extension format a year or so ago. So I like the idea of writing better introductions but there is a fine line for it getting too wordy. Feel free to brain storm, discuss, and use Reflection (or any other extension) as a testing ground for new ideas and marketing ploys. In summary: Your ideas sound nice, please continue.

Regards,
Philip

Reply via email to