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

[Gaarai]

You have some very good points Jennifer.

My desire is to create a standard that is used for all function 
references, template tag or not. The reason I'm frustrated by the Codex 
currently is that there isn't a standard by which all the pages are held 
to resulting in documentation chaos.

I'm trying to mentally weight the benefits and detriments with having 
the parameters below and the examples at top as opposed to the way I 
have it. On the one hand, using the current model does help those new 
people see the examples more quickly, but I wonder if these new 
coders/themers get used to that and never think about the power that the 
functions truly have due to being "insulated" from the parameters list 
and only being shown a very small sample of what functions can do.

I added a link to the Examples section in the Description section. 
Having something that overt toward the top, may assist those who just 
want to quickly see examples.

In my mind, the goal is to turn everyone who does more than just minor 
tweaks here and there into a WP developer, and I definitely think that 
this format is more usable than the current format. That said, I'm by no 
means a documentation expert; rather, I'm simply a coder that wants a 
better Codex and has finally taken up the initiative to try to create it.

Chris Jean
http://gaarai.com/
http://wp-roadmap.com/


Jennifer Hodgdon wrote:
> You might want to post this to the Doc list too (so I've cc'd that list).
>
> I personally like your new style better than the current style. It 
> annoys me all the time to have to scroll to the bottom to find the 
> argument list, the way some of the current pages have been organized.
>
> But if you are planning on using this for the functions known as 
> "Template Tags", you will need to get some feedback from less 
> technically-oriented viewers than the typical person on the Hackers 
> list. I think the way those pages are organized (with examples first 
> and the args way at the bottom) was chosen to avoid intimidating 
> themers who are just trying to do a little more with their themes but 
> might not be PHP or programming experts.
>
> So what I am trying to say is I think your style idea is great for a 
> programmer. :)   But we need to make sure to accomodate other 
> audiences for "template tag" functions.
>
> Regards,
>    Jennifer