[wp-docs] Introduction and Proposal

[Jacob Santos]

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