[wp-hackers] Codex function page proposal

[Gaarai]

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/



Jacob Santos wrote:
> I want you guys to pay attention, because this is most likely going to 
> be a long post and skipping parts will lose information. I would say, 
> it is a really bad idea, because I know so, but that argument doesn't 
> work with children, so I doubt it would work with adults.
>
> The problem with function documentation on the codex is even worse 
> than having it in the source code. At least in the source code, there 
> is a chance, albeit a slim one that the documentation will be updated 
> when a change is made. That is problem, most patches I've seen don't 
> bother updating the comments when the comments should be updated. What 
> makes you think they are going to take the time to update the codex 
> page either?
>
> You are duplicating efforts. I have committed to keeping the inline 
> documentation updated, I'm sure as hell not going to duplicate my 
> efforts for the codex as well. I figure it will take merely a week 
> before a release, to check to make sure that the documentation is 
> complete, that any new functions has documentation, and go through and 
> check and tighten up old documentation. I'm going to extend that time 
> further by updating the codex as well.
>
> Having the documentation on the codex was good, when inline 
> documentation was sparse and the function reference didn't exist 
> (http://phpdoc.wordpress.org/trunk/) I will suggest you link to that 
> for the parameters, return types, and other information already 
> contained in the function documentation site.
>
> I would rather see more of http://codex.wordpress.org/Shortcode_API 
> type pages. Function reference pages are only good when you know what 
> you are searching for. You have to know that the function exists, 
> before you can go to it. It is to remind you of information you 
> already know or to give you more information that doesn't exist 
> elsewhere. It is meant for programmers, but it is useless to 
> programmers without some companion to let them know they should be 
> looking for it.
>
> The reason the PHP function reference works, so well, is that it is 
> written in DocBook and contains codex type information, as well as 
> function reference type information. There isn't a function reference 
> for PHP, nor is there a codex (like WordPress has) for PHP. PHP just 
> has both in one. They don't duplicate efforts, because everyone's 
> effort is in the DocBook. Therefore, if there is a change, they just 
> do so in one place.
>
> Whereas for WordPress, you have two places, you already have the 
> function reference. Therefore, the parameters, return types, and other 
> miscellaneous function relevant information is known there. For the 
> Codex, I would rather like to see more examples. There is a reason I 
> didn't put examples in the inline documentation, I knew the codex was 
> the best place to put it. It is a place that has many contributors, 
> can easily be updated, and examples don't need to be changed or 
> updated often. If examples need to be updated, then a regression has 
> occurred and it is a defect that needs to be fixed or documented and 
> the example corrected.
>
> I figured that the best place to have documentation about parameters, 
> return types, and other information specific to the function was 
> inline to the function. I figured the best place to have the examples 
> was in the Codex. The reason there are sometimes examples in the 
> inline documentation is that there wasn't a codex page for the 
> function or it was someone else who thought it would be a good idea.
>
> No, the codex should have more pages like the Shortcode API Codex 
> page. Actually, there shouldn't really be very many function specific 
> pages either. It was my hope that the focus would be more on the 
> layman descriptions explaining the functions and examples on how to 
> use the functions than on parameters and return types.
>
> I am not much of a writer, I've tried to do this before and it is 
> terribly boring to me. I haven't even wrote the HTTP API Codex page 
> either. Really that is my fault, but I mean it isn't that difficult, 
> or at least it isn't to me.
>
> I've leave you with this gem. If you are not ready to babysit the 
> Codex parameter and return type information, then no one else is. If 
> you think for a moment that you will leave the community or abandon 
> the Codex effort, then don't do it. I think the reason you are doing 
> it, is because you think programmers pay more attention to the 
> Function Reference and I'll tell you that they don't. Programmers need 
> good, well written Codex style documentation as well, no matter the 
> skill level.
>
> The problem is always that function reference lacks context, which 
> examples provide, however what provides an even greater context is how 
> other functions go together. In this well, you establish a 
> relationship and make other functions related to the one known to the 
> developer and designer.
>
> I'll say that Designers need to have some programmer knowledge, so if 
> they are scared by a little function or whatnot, then they should hire 
> someone like me, who knows WTF he is doing! That said, any person 
> should understand the concepts given in an example and explained in 
> detail. Unless they wish to not understand and in that case, dressing 
> the verbiage in "designer friendly" terms doesn't seem acceptable to 
> me. Then again, I'm an asshole, so WTF do I care?
>
> Jacob Santos
> _______________________________________________
> wp-docs mailing list
> wp-docs at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-docs
>