[wp-testers] Re: [wp-hackers] Codex function page proposal
Kirk M
kmb42vt at gmail.com
Sun Dec 28 15:39:14 GMT 2008
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" <wordpress at santosj.name>
Sent: Saturday, December 27, 2008 9:47 PM
To: <wp-hackers at lists.automattic.com>;
<wp-testers at 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 at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-testers
More information about the wp-testers
mailing list