[wp-docs] Re: [wp-hackers] Codex function page proposal

[Jacob Santos]

As for the explanation as to why the comments are used is that usually 
are from people who don't have a php.net email account and don't want to 
or don't know how to submit a patch or ticket to correct the 
documentation. Also it is normally faster in any case to add a comment 
then it is to wait for the documentation page to be updated. Usually, 
any corrections in the comments that pertain to the documentation are 
usually just fixed and committed by those approving the comments.

Regardless, most of what the comments handles on php.net can just be 
dealt with by clicking on "edit" and modifying the text directly. For 
the other half, the discussion page can work, however, I suppose the 
complaint with that, is that you have to check it manually instead of 
being able to go down on the page to see. Therefore, you can probably 
assume that if "comments" were added to the discussion page, then most 
people will not be looking at it. Unless of course, the documentation 
doesn't make something clear, and then some of those will check the 
discussion to complain about the lack of information or clarity.

Jacob Santos

dave jaggy wrote:
> It looks like the effort does worth it. Although it's not quite what I
> expected or wanted it to be.
>
> I still think (and as it turned out - I'm not the only one who does),
> that user contributions in form of regular comments are very
> important. Many interesting things at php.net are found in comments
> and not in a description of a function itself. Comments may become a
> base for wiki entry. As I said, users make comments more easily then
> they write structured articles.
>
> I respect Charles and what he does right now, but I do not see how I
> can help. Perl is not my strong point and hence I can't contribute to
> the parser-script. The only thing I can do in established context is
> to edit texts on Function Reference page. Or, and that's more logical,
> I should start editing inline documentation?.. Maybe we should remove
> Codex Editing ability from Function Reference Part? Or somehow connect
> it with inline documentation? Otherwise we will again get two
> different and independent versions of documentation.
>
> I'm new to wp-docs, so that I haven't got a single letter from it yet
> for this conversation. Can anyone post anything, so that I could post
> a response to a corresponding thread?
>
>
> On Sat, Jan 3, 2009 at 5:40 AM, Jacob Santos <wordpress at santosj.name> wrote:
>   
>> Well, like I said, If you get it started, then I'll join in and walk beside
>> you on your journey to achieving enlightenment. I would rather join in once
>> I have time and I can contribute something that would only take a few hours
>> or so a week. I'd be happy to add a few examples and improve the details,
>> but that would mean that the page already exists.
>>
>> Your script will hopefully carefully update the existing codex pages and not
>> replace everything. The examples should always be applicable, unless there
>> is a regression or the specs change.
>>
>> Good luck.
>>
>> Jacob Santos
>>
>> Charles K. Clarkson wrote:
>>     
>>> Hello,
>>>
>>> I sent a copy of this message to the WP-Hackers list for reference. Let's
>>> keep further discussion on the Documentation list, please.
>>>
>>> Thank you.
>>>
>>>
>>> Jacob Santos wrote:
>>>
>>>       
>>>> You should have mentioned the Perl automated script.
>>>>         
>>> It started as a simple script with a few dozen lines that only I would
>>> ever use to skip over common sections in the Codex and blossomed into a
>>> multi-file, thousand line behemoth one long weekend. I didn't want to
>>> disclose it in its current condition. It's pretty slim on documentation.
>>> I did send Chris Jean a copy of it, however.
>>>
>>>
>>>       
>>>> Hmm, it seems that whatever you conclude on, it will be interesting.
>>>> Hopefully, the conclusion will be sooner rather than later, because I
>>>> don't think any one else will attempt what you guys are doing at the
>>>> moment or at least not in the near future.
>>>>         
>>> == Function Pages Planning ==
>>>
>>> I just read the December Archives on the Hackers list. It looks like
>>> there is some interest there by real life programmers and hackers who
>>> are more familiar with the WordPress code and PHP than I am. Together we
>>> should be able to come up with an easy to update version of the codex on
>>> both a sample site and in the Codex Function Reference.
>>>
>>> Hopefully we will use the inline documentation you started as our
>>> starting point and provide updates for it as we move forward.
>>>
>>>
>>> == Function Pages Progress ==
>>>
>>> I intend to continue adding new function reference pages to the Codex
>>> while we discuss implementation of future Codex Function Reference
>>> pages. I'd like to see something up on the Codex rather than nothing
>>> until we sort out the details. So, the planning phase shouldn't hold up
>>> the action phase. We will just have to do some back-tracking later on.
>>>
>>> I added about 82 new function pages in December. I hope to add more in
>>> January. Wish us luck and perseverance. We'll need both.
>>>
>>>
>>> Have A Happy New Year,
>>>
>>> Charles Clarkson
>>>       
>> _______________________________________________
>> wp-docs mailing list
>> wp-docs at lists.automattic.com
>> http://lists.automattic.com/mailman/listinfo/wp-docs
>>
>>     
>
>
>
>