[wp-hackers] Codex function page proposal
gaarai at gaarai.com
Sun Dec 28 05:06:19 GMT 2008
I don't like working without a plan, but if that's the best I can hope
for, I guess that will have to suffice.
I've removed the parameter, return, and error sections from my example page.
When I link directly to the function in the PHPdoc, it of course only
links to the inner-most frame. Is there/could there be a way to link to
the full PHPdoc site while having that internal frame show the desired
Please give me a tap on the shoulder when you've got ideas.
Jacob Santos wrote:
> Changes are not made by coders with commit access for PHPdoc. Anyone
> can create a patch on trac.wordpress.org to update, add, or replace
> the inline documentation. The design of the phpdoc site can be changed
> to that of the PHP site.
> I don't want to prevent work being done on the Codex to move this
> foward, my contention is just the parameter and return type. If you
> remove those then it should be fine with a link to the trunk phpdoc,
> since it will be up-to-date version.
> I would put more effort into the Codex, but like I said, it is
> extremely boring and time consuming. Most pages take at least four
> hours and I just don't have the time for that. Well, I do, but I'll
> rather spend it doing something else.
> The plan most likely will be from whoever puts for the effort and time
> to accomplish the task. Hashing out details is too time consuming and
> completely depressing. Trust me, with documentation, planning amounts
> to not doing and not doing equals to it never getting done. Only with
> putting one step forward will this be accomplished.
> I'll be walking beside you as will others, I believe, but I'm not
> going to be there at the beginning or even the middle. I don't expect
> others will be there with you either. However, setting a standard for
> which others can look at and parrot will do the Codex community a lot
> of good.
> Just keep the parameter and return types out of it.
> Jacob Santos
> Gaarai wrote:
>> Good stuff Jacob. This is the kind of information I need.
>> Since I had no idea of the scope of what you are doing with the
>> inline documentation until I read this, I'm sure that many other
>> people share the same lack understanding on what is going on with
>> that. Quite frankly, I could count on my fingers the number of days
>> that I even knew of the existence of phpdoc.wordpress.org.
>> So, we have a huge problem, and I think that the problem is even
>> bigger than I previously thought.
>> Here is what we have currently:
>> * The Codex
>> o Observations
>> + Changes can be made by anyone
>> + Creates a wealth of information
>> o Strengths
>> + Can find just references to just about anything a
>> developer would like to work with
>> + Includes function references, API references, and
>> general help documents
>> + Is often cited and thought of as the location to get
>> WordPress documentation
>> + Can be modified at any time
>> o Weaknesses
>> + The organization is poor at best. Everything is in a
>> mesh that is poorly linked. It's not difficult to find
>> more than one page with similar content that are
>> linked in completely different ways
>> + Search is next to worthless
>> + Much of the information is either severely out of
>> date, incorrect, or lacks quality examples of use
>> + Impossible to track staleness of content
>> * The PHPdoc Site
>> o Observations
>> + Changes can only be made by coders with commit access
>> to core
>> o Strengths
>> + Comprehensive list of every documented function and
>> class in WP Core
>> + Provides details that are helpful to coders
>> + More consistent and accurate information by comparison
>> to the Codex
>> o Weaknesses
>> + Not nearly as well known as the Codex
>> + The changes only occur when committed (this creates an
>> inability to update documentation on tagged versions)
>> + Has formatting issues (such as the presentation of
>> query-style parameter options)
>> + More limited scope when compared to Codex due to
>> smaller number of editors
>> It's clear to see that we have two systems that each have their
>> merits. My concept was limited in that it attempted to address the
>> shortcomings of the Codex without regards to the existence of the
>> I'm going to shelve my Codex ideas and plans for now. What we need to
>> do is discuss what the ideal solution for documentation is and then
>> begin implementing that. In other words, I now see that the problem
>> isn't just the Codex, it's the fact that there isn't a plan.
>> So, I don't know what needs to happen to create this plan and begin
>> executing it, but I would definitely like to be a part of it. What
>> most likely needs to occur is a number of us that are interested in
>> fixing the current state of WP documentation discuss ideas back and
>> forth until we come up with a vision of what WP documentation should
>> be and then create a plan to make that a reality.
>> Most likely, this will have to be taken over to the wp-docs site. I'm
>> sending this to the wp-hackers group since it started here, and I
>> want to get as many developers/designers in on this as possible.
>> Chris Jean
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
More information about the wp-hackers