[wp-docs] Re: [wp-hackers] Codex function page proposal

[Jacob Santos]

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