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

[Charles K. Clarkson]

Gaarai wrote:

 > My desire is to create a standard that is used for all function
 > references, template tag or not. The reason I'm frustrated by the
 > Codex currently is that there isn't a standard by which all the pages
 > are held to resulting in documentation chaos.

I found the same thing a couple of months ago. One problem with the
Codex is that there are almost 1900 WordPress functions (not including
Classes). Maintaining a standard for that many pages in a wiki is bound
to be difficult, if not impossible.


 > I'm trying to mentally weigh the benefits and detriments with having
 > the parameters below and the examples at top as opposed to the way I
 > have it.

I toyed with placing the examples higher up on the page, but the Table
of Contents (TOC) kept getting in the way. With a few examples in it,
the TOC gets really long and pushes the first code box way down the
page. The same problem results with the Usage section if there are a lot
of parameters, but there is no descriptive text in the Usage section.

The problem with a well-written example is that there will probably be
some descriptive text above the code section which is more convenient if
it remains near the code section. To avoid unnecessary wrapping the
Codex page style pushes the first code box down below the TOC. The
result may be a huge amount of whitespace between descriptive text and
the code box.

The reader can correct this behavior by hiding the TOC, but that may not
work on all browsers and it has to be selected on each page. (There's no
cookie for it). Navigating away from the page will require hiding the
TOC again.

 > Eventually, I found that the PHP Function Reference, has what I
 > consider the most straightforward, intuitive function documentation
 > style.

I have a dedicated button in my Firefox browser to jump to the PHP docs
you mention [2]. I wish there was something similar for other
programming languages, but I do sometimes go nuts trying to figure out
the data type of the return value of many PHP functions. It's just not
in the docs many times.

I find the PHP docs are missing some uniformity between function
definitions. I am often left with unanswered questions after reading the
docs.


When I first started editing the Codex function reference I had
something like the following in mind. It's based on the Template Tags
sections. Your See Also section is my Related section.

== Description ==
== Usage ==
== Examples ==
== Parameters ==
== Return Values ==
== Notes ==
== Change Log ==
== Source File ==
== Related ==

After writing a few dozen function pages I changed it to this so that
the Examples section would clear the Table of Contents more often.

NOTE: I was not aware of the Trunk [4] auto generated documentation
       before now.

== Description ==
== Usage ==
== Parameters ==
== Return Values ==
== Examples ==
== Notes ==
== Change Log ==
== Source File ==
== Related ==

After some consideration I think Usage, Parameters, Return Values should
remain together. We could place those in one big section:

== Usage ==
=== Parameters ===
=== Return Values ===

Using a cookie, we could auto hide that section for people who would
rather not see it at first.

Reading the past posts, it seems like special things like cookies are
not easily added.

The Table of Contents allows the reader to jump to a favorite section,
like the Examples.

My Notes section contains information on cross-reference items like
which WordPress functions this function uses and which global variables
are used or manipulated. Those portions of that section are mostly
auto-generated from the source.

My Source File section is a personal preference. I always want to look
at the source code while developing and some functions are in files
which make little sense from their names. We could also add it to the
Usage block. SO could the Change Log.

== Usage ==
=== Parameters ===
=== Return Values ===
=== Source File ===
=== Change Log ===

This would reduce the top level sections to the following.

== Description ==
== Usage ==
== Examples ==
== Notes ==
== Related ==

If the Codex author could change the Table of Contents on the function
reference pages to show only the top level sections and not the sub-
sections, the TOC would always be short enough to avoid the whitespace
gap I mentioned above. We could then use your example centric style.
This would also place the Notes next to the Usage which seems more
appropriate.

== Description ==
== Examples ==
== Usage ==
== Notes ==
== Related ==


The Parameters section has a lot of white space in it and too much bold
text for my tastes. It is written using the Parameter Template [1], so
its style and HTML could be changed to make it more concise without
editing each function in the Codex. It would be nice to have a similar
Template for Return Values and the Usage sections as well.

I can write a script that will change the order of the function
reference page sections across the whole Codex function reference, so
don't be afraid to make a change in the section order.

As I stated in another message, I use a parser to generate much of the
function page sections directly from the source code, so maintenance
may not be as much a problem as it may first appear.



Additional Thoughts:

It would probably be better for this and future documentation projects
to generate XML from the WordPress source code. Future Codex editors
could then use that XML source to customize references. Writing a XML
standard for that is beyond my current skills, but common source files
have a lot of appeal.

The program which produces the Trunk [4] (phpDocumentor) might be a good
candidate for producing the base XML files. Examples, Descriptions and
Notes would still require human editors to maintain relevant
documentation, but could be left in the XML files to allow more robust
WordPress documentation projects down the line.

As Jacob has stated, we need to avoid duplicate effort, not because it
is is inefficient, but because we all will eventually move on to other
projects and we need to find the easiest path to keeping the Codex up to
date now and in the future.

You mentioned code syntax highlighting in your example page [3]. With a
publicly available XML file of the WordPress function docs it isn't much
of a stretch to see a WordPress plugin which could use one of the
textarea plugins to display up to date WordPress documentation in the
Admin area of the users own blog complete with links to other sources
and syntax highlighted examples customized to the users preferences.

[1] http://codex.wordpress.org/Template:Parameter
[2] http://us2.php.net/manual/en/funcref.php
[3] http://codex.wordpress.org/User:Chrisbliss18/wp_cache_add
[4] http://phpdoc.wordpress.org/trunk/

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