[wp-docs] Introduction and Proposal
Charles K. Clarkson
cclarkson at htcomp.net
Sat Nov 29 16:34:33 GMT 2008
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
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.
Mobile Home Investor
Free Market Advocate
+1 (254) 968-8328
More information about the wp-docs