[wp-hackers] Codex function page proposal

[Jacob Santos]

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/
>