[wp-docs] Introduction and Proposal

[Jacob Santos]

As a developer, I hold no distinction between the so called "Template 
Tags" and functions. Besides the fact that normal end users might run 
away screaming, if they heard the term "function" but not with these 
"template tags".

As a developer, it was equally confusing to me to hear "template tag" 
when the person meant "function". I think the intention was well 
meaning, but I find that when you try to dumb down terminology, even 
technical, you must ensure that the origins of said end user terminology 
is known. I had this discussion with an end user, before I knew WTF he 
was talking about on a podcast and had to do research. It was before I 
really worked on any theme or used the codex.

That said the purpose of the codex is to bridge the gap of technical 
information and developer and user guides for how-to do something. It is 
increasingly difficult to navigate the phpDocumentor sites the more you 
are unsure of what you are looking for. The codex is to hold the 
visitors hand while educating on what is possible. In that, better 
examples should be given on the codex than what can be made in the 
inline documentation. I do not have the fortitude to write the time 
consuming articles on the codex, so I bow to anyone that does.

It was my goal back when I didn't realize how long it would take to put 
together the inline documentation. However, I mean, for the longest time 
it was me and patches from other contributors that only had to be 
cleaned up. Towards the end more contributors came to task, but by that 
point was already putting the finishing touches. The total amount of 
people amounts to about half a dozen over the past two or three years 
(there were some really old patches, couple were no longer relevant or 
wrong).

What I mean to say, is that I would rather see more examples on how to 
use functions than parameter documentation on the codex. Parameter 
documentation is difficult enough to maintain in the inline 
documentation without having to look up the page that the function is 
documented on in the codex. I believe more people focus their energies 
on the codex, so theoretically, more people will carry the burden of 
work. Hell, I might be willing to do a few pages myself. Not now. The 
second stage of the inline documentation in the WordPress source for the 
wp-admin files has yet to conclude.

I think the Developer Guide documentation on the codex can be improved. 
I think it might be better to create a Theme Guide documentation also 
for those who want to only focus on modifying their theme and don't want 
or care about the developer side of the functions and documentation. I 
researched several ways to do this, but I've yet to obtain the karma on 
the codex to create something entirely new. Or at least to get it up to 
the point where it would be worth creating a section for it.

Inline documentation wasn't so much difficult as it was time consuming. 
When you write something like an article on the codex, you add 
additional constraints of difficulty and it is somewhat boring, because 
you have to make sense. I tend to ramble about nothing, which doesn't 
make for a well written article.

Jacob Santos


Malaiac wrote:
> 2008/11/30 Jacob Santos <wordpress at santosj.name>:
>   
>> The way I envisioned it, was that the codex would link to the function
>> documentation and extend it with examples. It took me a good year to
>> complete the inline documentation with the source, so I hope that the time
>> spent will prevent you from doing likewise. I also had selfish reasons for
>> my involvement with the inline documentation and for it appears the same
>> reasons you have for working on the codex.
>>
>> Good luck to you. Most people will want to use the codex before diving into
>> the function documentation.
>>     
>
> do we need documentation for tags AND functions ?
>
> imho, only webmasters with some knowledge of php/mysql need to access
> function documentation. The huge work made on inline doc *bows to
> Jacob Santos* answers those questions.
> "regular" users (webmasters who do not want to bother with php) only
> use template tags and general documentation.
>
> I'd vote with both hands to not maintain parallel documentations
> (inline + codex) on functions.
>
> Malaiac
> _______________________________________________
> wp-docs mailing list
> wp-docs at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-docs
>