[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