[wp-hackers] documentation

[jill]

Jason goldsmith wrote:

>The Wiki helps....
>
>Seriously, get a copy of phpXref and run it against your install. It
>makes life so much easier. I find that it helps more than anything
>else. The WordPress code is pretty good in most places.
>
>I was a bit irritated when I started with the lack of docs, but unless
>someone wants to write technical docs instead of coding, I think we
>are going to have to live with the sparsity and try our best to
>contribute hints where we can.

It's absolutely true that documentation is a very different talent and requires a very different
focus. Tech writers find work for a reason, after all. I find inline commenting to actually
disrupt my understanding of what the code is doing, and very much prefer such details in
headings prior to various functions and so forth. Even so, it's not the same as providing
useful docs.

Last night I was running searches on the forum on '$single', hoping to find something
definitive on '$somthingotherthansingle,maybecatorplural' and ended with an inference
that $cat is in fact a (maybe) global that distinguishes category page views from all the other
varieties. If WP had a tech writing team whose interests and availability matched that of the
dev group, stuff like that would be indexed to the point of being blazingly obvious to the
most inept seeker. But documentation always plays catch-up to development, it's just the
nature of the beast. WP development has yet to settle down long enough for documentation
efforts to get a grip on everything that's been so far coded.

>>  (Matt wrote)
>> > To be fair all the developers, including myself, had to go through this at
>> > some point. When Mike and I picked up the b2 code to work on what would
>> > become WordPress there were large parts of the code that we had no
>> > familiarity with at all. A lot of .70 was us just figuring out what was
>> > going on. :)

I applaud your tenacity. Seriously. But with respect, that's not the situation plugin writers are
in, or ever will be in. For the most part, we won't be topping, or leading, the curve. All the
study in the world won't make that so. We're in a continual catch-up position.

As Jason Goldsmith observes, "Running against nightlies isn't always helpful because it may
not match what a developer is working with." Too right, it won't. That way lies madness.
IMHO, if you're having to play catch-up anyway, you're best off playing against the last
stable release, than trying to keep up with (possibly contradictory) nightly changes.

Everyone wants docs until they have to write them, me included. It can be one of the most
frustrating phases of developing tools. Docs don't happen, though, for the wishing;
someone or some group has to be as focused on them as the dev group is on coding.

pericat
-- 
<http://pericat.ca/>