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.