Re: [wp-testers] Re: [wp-hackers] Codex function page proposal
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
[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!
