[wp-hackers] Codex function page proposal

dave jaggy jayarjo at gmail.com
Sun Dec 28 07:21:27 GMT 2008


Very interesting discussion here. Personally I had a very hard time
starting with WordPress API and I can't say that Codex helped in that,
sometimes it took me to wrong places, sometimes it still does. I never
knew about the http://phpdoc.wordpress.org/trunk/. That's great thank
you. It's much more easier then browse an API in search of comments.

But I still think that the whole thing is little misleading. One can
become experienced PHP coder without entering the API directly. I
don't think that everyone has enough motivation and courage to do so
anyway. But in WordPress world it's kinda - 'you just have to do it'.
There seems no other way to really understand what exactly is
happening and why.

I think, that documentation must be one and it has to be automated, at
least at code comments level. Why not move to PHP-like documentation
style, but - leave a space for user contiributed descriptions and
examples. We can do it on the same page. For example, there will be
only phpdoc version of function description, until someone decides to
contribute additional information. And let it be added underneath the
phpdoc piece and let it be denoted that is is USER CONTRIBUTED and
that you guys at WordPress core are not responsible for what is
written down there ('cause it's really is not self-explanatory).

So there can be two parts on every page - phpdoc one which will be
updated automatically when patch will be done, and user contributed
wiki. And there can be a third one - comments (raw ideas - people post
comments easily, I mean working on wiki needs some kind of
preparation, and posting a comment does not). Someone more skilled in
writing may take those comments later and comile good wiki part out of
them.

I think that's the best structure. I would use it with great relieve I
should say.

On Sun, Dec 28, 2008 at 9:06 AM, Gaarai <gaarai at gaarai.com> wrote:
> 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
>>
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>


More information about the wp-hackers mailing list