Hi Jacob,
Understanding that you must be having a "discussion"
pertaining to or in relationship to the WordPress Codex
(always a touchy subject, worse than "discussing" the WP
forums) at the "wp-hackers" list, I'm wondering if you perhaps
sent your reply to the ongoing discussion to the wrong list?
Considering how out of context it is to the current
"wp-testers" threads I just thought you might have. ;)
Good points though and thanks for the link to the PHP Docs.
Didn't even know they existed...which, I assume from the
subject of your email, must be a major portion of the
discussion you're having over at the "wp-hackers" list.
And your work is always appreciated. :)
--------------------------------------------------
From: "Jacob Santos" <wordpr...@santosj.name>
Sent: Saturday, December 27, 2008 9:47 PM
To: <wp-hack...@lists.automattic.com>;
<wp-testers@lists.automattic.com>
Subject: [wp-testers] Re: [wp-hackers] Codex function page
proposal
I want you guys to pay attention, because this is most
likely going to be a long post and skipping parts will lose
information. I would say, it is a really bad idea, because I
know so, but that argument doesn't work with children, so I
doubt it would work with adults.
The problem with function documentation on the codex is even
worse than having it in the source code. At least in the
source code, there is a chance, albeit a slim one that the
documentation will be updated when a change is made. That is
problem, most patches I've seen don't bother updating the
comments when the comments should be updated. What makes you
think they are going to take the time to update the codex
page either?
You are duplicating efforts. I have committed to keeping the
inline documentation updated, I'm sure as hell not going to
duplicate my efforts for the codex as well. I figure it will
take merely a week before a release, to check to make sure
that the documentation is complete, that any new functions
has documentation, and go through and check and tighten up
old documentation. I'm going to extend that time further by
updating the codex as well.
Having the documentation on the codex was good, when inline
documentation was sparse and the function reference didn't
exist (http://phpdoc.wordpress.org/trunk/) I will suggest
you link to that for the parameters, return types, and other
information already contained in the function documentation
site.
I would rather see more of
http://codex.wordpress.org/Shortcode_API type pages.
Function reference pages are only good when you know what
you are searching for. You have to know that the function
exists, before you can go to it. It is to remind you of
information you already know or to give you more information
that doesn't exist elsewhere. It is meant for programmers,
but it is useless to programmers without some companion to
let them know they should be looking for it.
The reason the PHP function reference works, so well, is
that it is written in DocBook and contains codex type
information, as well as function reference type information.
There isn't a function reference for PHP, nor is there a
codex (like WordPress has) for PHP. PHP just has both in
one. They don't duplicate efforts, because everyone's effort
is in the DocBook. Therefore, if there is a change, they
just do so in one place.
Whereas for WordPress, you have two places, you already have
the function reference. Therefore, the parameters, return
types, and other miscellaneous function relevant information
is known there. For the Codex, I would rather like to see
more examples. There is a reason I didn't put examples in
the inline documentation, I knew the codex was the best
place to put it. It is a place that has many contributors,
can easily be updated, and examples don't need to be changed
or updated often. If examples need to be updated, then a
regression has occurred and it is a defect that needs to be
fixed or documented and the example corrected.
I figured that the best place to have documentation about
parameters, return types, and other information specific to
the function was inline to the function. I figured the best
place to have the examples was in the Codex. The reason
there are sometimes examples in the inline documentation is
that there wasn't a codex page for the function or it was
someone else who thought it would be a good idea.
No, the codex should have more pages like the Shortcode API
Codex page. Actually, there shouldn't really be very many
function specific pages either. It was my hope that the
focus would be more on the layman descriptions explaining
the functions and examples on how to use the functions than
on parameters and return types.
I am not much of a writer, I've tried to do this before and
it is terribly boring to me. I haven't even wrote the HTTP
API Codex page either. Really that is my fault, but I mean
it isn't that difficult, or at least it isn't to me.
I've leave you with this gem. If you are not ready to
babysit the Codex parameter and return type information,
then no one else is. If you think for a moment that you will
leave the community or abandon the Codex effort, then don't
do it. I think the reason you are doing it, is because you
think programmers pay more attention to the Function
Reference and I'll tell you that they don't. Programmers
need good, well written Codex style documentation as well,
no matter the skill level.
The problem is always that function reference lacks context,
which examples provide, however what provides an even
greater context is how other functions go together. In this
well, you establish a relationship and make other functions
related to the one known to the developer and designer.
I'll say that Designers need to have some programmer
knowledge, so if they are scared by a little function or
whatnot, then they should hire someone like me, who knows
WTF he is doing! That said, any person should understand the
concepts given in an example and explained in detail. Unless
they wish to not understand and in that case, dressing the
verbiage in "designer friendly" terms doesn't seem
acceptable to me. Then again, I'm an asshole, so WTF do I
care?
Jacob Santos
_______________________________________________
wp-testers mailing list
wp-testers@lists.automattic.com
http://lists.automattic.com/mailman/listinfo/wp-testers
_______________________________________________
wp-testers mailing list
wp-testers@lists.automattic.com
http://lists.automattic.com/mailman/listinfo/wp-testers
