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 <[EMAIL PROTECTED]>:
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
[email protected]
http://lists.automattic.com/mailman/listinfo/wp-docs
_______________________________________________
wp-docs mailing list
[email protected]
http://lists.automattic.com/mailman/listinfo/wp-docs
