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

[Lorelle VanFossen]

While Jacob's colorful response is right in most cases, the other long time
members of the Codex volunteer team are also right. We've got a lot of
redundant effort when it comes to documenting functions, template tags, and
such, often to the distress of other contextual needs in the Codex. The
structure originally set by Kaf and others, similar to what Chris and
Charles are working on, did come from the PHP manuals as a key example.

Getting the inline documentation into a "readable" format is critical,
especially if it is easily updated. Whether that is integrated into the
Codex or a separate medium will be up to those who choose to maintain it at
the current time. It may evolve into something else later as technology and
volunteer ability changes, but the key is to connect the two together,
rather than duplicate effort.

The key to the WordPress Codex is the word "manual." It is a guide to help
people use WordPress, from just blogging to writing Plugins and developing
Themes. WordPress is moving away from core hacking into third-party
enhancements, and it is up to the documentation team to make it easy for
those third-party folks to understand how to hook into WordPress, but
equally, how to use the most basic of functions and a little bit more.

A lot of people have taken on the burden of redoing all of the function
pages, losing track midway through. It's a LOT to take on. I think it's
important to set a core style, which has been done, and then update the
information rather than redo. It's a lot of upkeep. Highlighting the most
commonly used functions WITH EXAMPLES is key to helping people learn how to
use them. That makes the Codex important to those who use it, and the inline
docs project is critical to those who want to dig deeper, and much applause
needs to go to Jacob for his determination to see that project through. It
was a herculean effort and we are all proud of you, Jacob, in spite of being
a teddy bear ass. :D

If Chris and Charles can work together to create a core format, and update
ALL the pages accordingly, and then continue the work with the most popular
and common functions, we'll cheer you on as well. We love everyone who takes
a few minutes of their time to help improve the Codex and supporting
documentation. Let's just avoid duplicating effort to slow the burn out and
frustrations.

For historical reference on functions and hooks projects, see:

http://planetozh.com/blog/my-projects/wordpress-functions-implementation-history-tool/
http://blog.ftwr.co.uk/archives/2007/12/28/tracking-deprecated-functions/
http://sandbox.ftwr.co.uk/doc/
http://www.dbswebsite.com/design/wordpress-reference/
http://asymptomatic.net/2005/04/22/1503/ezstatic-20-and-pluggable-functions/
http://blog.taragana.com/index.php/archive/wordpress-2x-hooks-for-action-comprehensive-list-for-plugin-and-theme-developers/
http://blog.taragana.com/index.php/archive/wordpress-2x-filters-comprehensive-list-for-plugin-and-theme-developer
http://wphooks.flatearth.org/
http://wordpress.taragana.net/index.html WordPress Source Code
http://adambrown.info/p/wp_hooks

Only a few of the attempts to document hooks and functions in WordPress that
I've kept up with.

Lorelle
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://comox.textdrive.com/pipermail/wp-docs/attachments/20081228/7f89c178/attachment.htm