[wp-hackers] Codex function page proposal

[Gaarai]

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 
function?

Please give me a tap on the shoulder when you've got ideas.

Chris Jean
http://gaarai.com/
http://wp-roadmap.com/


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 
>> PHPdoc.
>>
>> 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.
>>
>> Thoughts?
>>
>> Chris Jean
>> http://gaarai.com/
>> http://wp-roadmap.com/
>>
>
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>