[wp-docs] Introduction and Proposal

[Charles K. Clarkson]

Lorelle on WordPress wrote:

> That was the goal, however, we "should" be liking to the explanation 
> documentation of "writable" and such to save some words and speed up the 
> process for those who understand how these things works.
> 
> You make an assumption that those digging into the template tags and 
> functions have no idea what they are doing.

That's a bit harsh. I make the assumption that even competent function 
page authors do not have a common written standard or framework from 
which to write their descriptions. They may be very competent writers 
and editors, but I think a function reference should be consistent from 
function to function.

I didn't investigate template tags because the Codex assumes that are 
already good examples of what tag pages should look like. I based my 
functions standard on my perception of the template tags pages.


 > By the time someone gets to
> those pages, they have some ideas, so we have to be careful not to bore 
> those who do. :D Linking is a key way of connecting all the educational 
> content together without boring the intermediate user or overwhelming 
> beginners.

That was a problem I had with the example page. The page editor seem to 
assume that readers would be using a dated version of WordPress. That 
sort of information is better left near the bottom of the page.

I can understand the editor's problem. The code for that function had 
just been changed and he might have spent hours trying to figure out why 
his code had suddenly broken. He wanted to give others a heads up to the 
change, but chose a poor way to do it.

I originally started to make changes to that page, but stopped as I 
realized there might be a standard out there for these pages that I did 
not know existed. My page changes had quickly evolved changing the 
entire page and I decided to look before I leaped.


> I like your style and it sounds like it would be wonderful for the tags 
> and functions. We worked very hard for a long time to give quality 
> VISIBLE examples, and I recommend generically styled screenshots or 
> screencasts now in these pages to help show examples of usage rather 
> than duplicating them exactly with inline CSS as was originally done. We 
> need to incorporate more of the visible to serve that audience in the Codex.

If by "screencasts" you mean a read-only picture of the code then I 
would disagree. Programmers need to be able to Copy & Paste code 
examples to their test rigs.

If you mean the result of an example should be shown a screen shot then 
I feel you may be scaring some authors away. It's a lot easier to Copy & 
Paste output than to upload and use a screen shot image.

Of course, even without a common standard, there is no rule that says 
one page author has to write the entire page. Someone else could always 
come back and update the examples.


> Thanks for taking this on. This sounds wonderful. What a wonderful gift 
> to give back to the WordPress Community.

Actually, my motives are very selfish. Currently, I know only a tiny 
number of functions in the WordPress API. By updating and eventually 
creating about 20 function pages per month I will need to research how 
the functions work and increase my working knowledge of the API.

I have found that my own self-interest keeps me motivated much longer 
than altruistic goals do. YMMV.


 > Let me/us know how we can help you through the process and if you have
 > any questions.

My main question is whether an experienced editor of the Codex might see 
a potential problem with my suggested standard. Other than that I am 
biting off too much for my first outing. :)

I don't want to edit two months worth of articles to find that I had a 
fatal flaw that an experienced editor could have spotted months earlier, 
but will now take hours of editing all the new edits to fix.


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