To answer your question, it would be both better to have screencasts and
written examples. That way programmers and normal users can see the
results of said copied and pasted code.
To answer your other questions, you may want to check out
http://phpdoc.wordpress.org and http://phpdoc.ftwr.co.uk for function
reference and might give you a head start since some of the work has
been done for you.
The way I envisioned it, was that the codex would link to the function
documentation and extend it with examples. It took me a good year to
complete the inline documentation with the source, so I hope that the
time spent will prevent you from doing likewise. I also had selfish
reasons for my involvement with the inline documentation and for it
appears the same reasons you have for working on the codex.
Good luck to you. Most people will want to use the codex before diving
into the function documentation.
Jacob Santos
Charles K. Clarkson wrote:
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
_______________________________________________
wp-docs mailing list
[email protected]
http://lists.automattic.com/mailman/listinfo/wp-docs
