Hello,
I am new to the list, but not to WordPress, PHP or programming. I
have a strong Perl, CSS, HTML background. I have been playing with PHP
for about year and have several WordPress installations running.
I would like to tackle editing some the individual function pages
like http://codex.wordpress.org/Function_Reference/add_option. I can
spend an hour or two each weekday in December editing pages and perhaps
move on to create missing pages after I get my feet wet.
I would first like to discuss a standard page structure. I looked at
the reference material on Codex style, one year of list archives and
the Template Tags reference. It seems the typical page structure for a
Template Tag is as follows (this example came from:
http://codex.wordpress.org/Template_Tags/the_content):
== Description ==
== Usage ==
== Examples ==
=== Example 1 ===
=== Example 2 ===
=== Example 3 ===
== Parameters ==
== Related ==
{{Tag Post Tags}}
{{PHP Function Tag Footer}}
I think I would prefer to assume:
* Any documentation is obsolete the moment it is posted.
* The reader is using the latest stable version of WordPress.
* The reader is not a professional or experienced programmer.
* This is the first page the reader has viewed in the Codex.
* The reader wants to know where the function is defined within the
source code.
* 3 good examples of a function is wishful thinking. :)
Here is a proposed outline of what I'd like to see in for individual
function pages. While I know what I want form the Codex, I don't know
what others might want. I do know that I don't want to start editing
pages without a least a hint of a plan.
Also, is there an easy way to report the date this page was last
updated? Or which WordPress version was active when it was last updated?
== Description ==
Tell the reader what this function does at the time this description
was written without jargon or abbreviations. Don't, for example,
assume the reader knows what a rewrite rule is.
== Usage ==
%%%<?php usage goes here ?>%%%
%%%<?php usage goes here ?>%%%
%%%<?php usage goes here ?>%%%
== Examples ==
=== Example 1 ===
=== Example 2 ===
=== Example 3 ===
== Parameters ==
This function does not accept parameters.
- or -
=== Parameter 1 ===
=== Parameter 2 ===
=== Parameter 3 ===
== Recent Changes ==
Recent changes in this function's use. Like recently deprecated
parameters; Recent version changes; Recent database changes; Recent
philosophical changes; etc.
== Source File ==
Which source file defines this function.
== Related ==
{{Related Function Group}} (These tags doesn't exist)
{{PHP Function Footer}} (This tag doesn't exist)
HTH,
Charles Clarkson
--
Mobile Home Investor
Free Market Advocate
Programmer
Stephenville, TX
http://www.clarksonenergyhomes.com/wordpress/about/
http://twitter.com/CharlesClarkson
+1 (254) 968-8328
_______________________________________________
wp-docs mailing list
[email protected]
http://lists.automattic.com/mailman/listinfo/wp-docs
