Code flow doc (was: Re: [wp-hackers] Google Summer of Code 2008)

[Dan Larkin]

Well, I do understand what you're saying about it going out of date.  That
is the main problem with documentation - that it needs to be maintained.
This is true of inline documentation as well.  It's never really an easy
process.

My point to making this documentation wouldn't be to facilitate the core
developers.  They obviously already know how things work.  As I said, I'm
proposing it to help out the casual developers - the people who are trying
to write a plugin or two for their site, but can't figure out how to make WP
do what they want, or the people who are trying to figure out what filter
they really need to, or to add extra functionality that they would have
thought should be in the core but they found isn't.  I know from my limited
experience writing plugins for WP, it can be pretty frustrating trying to
figure out how the actual code handles things that are pretty simple when
talking on the abstract level, just because things are sent around through
so many different functions and filters.  I mean, yes, you can use search
tools to figure out which file a function is in, but when you have to do
that like twenty times and figure out what each function is doing along the
way, it can be pretty discouraging.

Think of the WP motto.  "Code is poetry."  Yes, specially trained readers
(and/or literary geniuses) can read a poem, analyze it, and come out with
the meaning quite quickly.  Take a high school class.  You have a couple
kids who are going to end up as English majors.  You won't find them
complaining.  There's twenty-odd other kids in that class though.  Sure,
maybe ten of them don't give a crap about poetry, but there's others that
would love to get the meaning and just are having trouble with it.  They can
get it eventually, but it takes them a lot longer.  That's what Sparknotes
are for.  That's what I'm proposing.  And while they may not rely on it,
those couple future English majors like having Sparknotes around every now
and then as a quick reference.  It benefits everyone.  The only person who
really suffers is the one making the notes, since he or she has to shell out
the time.  I realize this analogy breaks down where poetry usually doesn't
change so much so often, but that just means more time spend by the
note-takers.

Once the main effort is put out once (which a full-time job for a summer
should be quite a step in that direction), then only a fraction of it must
be spent with each subsequent code release.

Maybe I'm trying to cater too much to the entry level WP hacker for the
taste of those on these lists (since most people here are veterans), but
it's my two cents so I'm throwing it out there.

:: Dan Larkin

On Tue, Feb 26, 2008 at 1:00 PM, Jennifer Hodgdon <yahgrp at poplarware.com>
wrote:

> 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-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>