Dan Larkin wrote [snipped]:
[...] I guess my aim is to
completely flesh out that Query Overview page, and then some.
It does a good job of starting the explanation, at least for the non-admin
pages. What I'd like to see is a group of pages that explains not only what
the main functions are, but also what these functions do in detail. I'd
like to see a document specify which filters and hooks are run at which
point in the process, and what they can be used for. I'd like to see
case-specific data paths. [...]
From what I understand, WP is designed to be accessible. A project with as
many lines of code as WP is inherently inaccessible. In economic terms,
it's an oligopoly for experienced developers - there is a pretty high
barrier to entry [...]
A few more thoughts here...
Yes, there is some barrier to becoming familiar with the core
WordPress code base, but that is true in any large-ish open-source
project. If you want to participate in the role of a core developer or
bug patcher in any open-source project, you have to be willing to read
source code. Is that a problem? I don't think so -- only people who
have familiarized themselves with the core source code and who can
read reasonably well-written code in the project's language should be
proposing changes to it, and yes, it does take time to familiarize
yourself with any fairly large code base. The code of WordPress is
written in a pretty clear manner, in my opinion... It could be better
documented (there are efforts underway to add PHP Doc headers to all
the functions, another good SoC project), but if you can read PHP, I
don't think it's difficult to figure out what any individual function
does by reading the code.
Also, if you have a reasonable IDE on hand (such as Eclipse), if there
are functions called that you are unfamiliar with, it's pretty easy to
search for them and find out what they do.
My thought when I wrote the Query Overview page was to present a road
map to how visitor-facing pages are generated, which I didn't think
was obvious, even after spending the time to read through the code in
detail. I thought that at least it would give someone a head start (at
least tell them where in the source code to read to find more details).
The reason I haven't made something like Query Overview to explain
what the admin pages do, is that I think it's a lot clearer there: you
visit a particular admin page URL, and that tells you which source
file is being used to generate that page. Then go read that file to
see what it does.
My concern on making a document like what you describe, which goes
into great detail on the flow, functions, hooks, etc., is that my
experience in years as a professional software developer has been that
the code itself is the only reliable "documentation" of what the code
is doing in detail. Any attempt at having outside documentation
explaining the code may be fine at the moment it's written, then
quickly goes out of date.
Thoughts?
Jennifer
--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal/WordPress Sites, Themes, Modules/Plugins
Custom Web Programming, Web Databases
Modeling/Analysis/Palm OS Software
_______________________________________________
wp-docs mailing list
[email protected]
http://lists.automattic.com/mailman/listinfo/wp-docs
