atom feed6 messages in net.php.lists.phpdocRe: [PHP-DOC] user notes: code snippets
FromSent OnAttachments
Philip OlsonApr 8, 2010 12:28 pm 
Peter CowburnApr 8, 2010 1:21 pm 
Hannes MagnussonApr 9, 2010 6:30 am 
Daniel BrownApr 9, 2010 6:34 am 
Philip OlsonApr 9, 2010 12:08 pm 
Christopher JonesApr 12, 2010 12:36 pm 
Subject:Re: [PHP-DOC] user notes: code snippets
From:Philip Olson (phi@roshambo.org)
Date:Apr 9, 2010 12:08:58 pm
List:net.php.lists.phpdoc

On Apr 9, 2010, at 6:31 AM, Hannes Magnusson wrote:

On Thu, Apr 8, 2010 at 20:22, Peter Cowburn <pete@gmail.com> wrote:

On 8 April 2010 20:29, Philip Olson <phi@roshambo.org> wrote:

* We don't plan on becoming a full blown code repository, or do we? Worth
worrying about?

I think it is worth worrying about; with all this discussion I fear we're going to be placing more community-emphasis on the user notes, snippets, comments-on-notes-and-snippets, etc. than on (improving) the documentation itself. That might be a good thing (community involvement always is) or bad (it is *the manual*, after all).

Most these ideas seem to be promoting the notes as a code library. I don't think thats what we want and are striving against.

Its ok to have random snippets, related to the documentation in question, just to showcase how to use it, what its purpose is and so on, but that is where I used to draw the line. I don't want this to turn into code library. All I want when I read the notes is extra information, paraphrasing, short usage examples, and possible tips&tricks.

We accept code snippets as a type of user note, and since we'll [likely] tag
them we can deal with them a little differently. Either we accept code snippets
or we don't, and if we do, let's treat and accept them as such. This does not
mean it's a code repository, but this does mean we can make them more useful.

And the idea isn't to place an emphasis on user notes, but rather it's to
improve them and help users help themselves. Code snippets are the most complex
type of note so they deserve increased planning, which is what we're doing now.
And although constructive criticism is extremely welcomed, additional and
different ideas for implementation are encouraged, because I think we're
actually going to implement something this time.

Regards, Philip