[wp-docs] Introduction and Proposal

[Charles K. Clarkson]

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