Re: user notes: code snippets

On Thu, Apr 8, 2010 at 20:22, Peter Cowburn <petercowburn@gmail.com> wrote: > On 8 April 2010 20:29, Philip Olson <philip@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. >> And lastly, one problem about coding examples is how good practice can dilute the example. >> So for example, while teaching people about $_GET['foo'] we may end up with one of: >>  A) echo htmlspecialchars($_GET['foo'], ENT_QUOTES, 'UTF-8'); // Hello >> World >>  B) echo $_GET['foo']; // Hello World >> >> The (A) dilutes the idea of $_GET whereas (B) is clear. So which is the better example? >> Probably (A) in this case but the point is it's not straightforward. > > Both snippets are demonstrating different ideas (escaping output > versus a simple example of using $_GET). It would help if when adding > snippets, the reason for/behind it is made clear: am I just posting a > super-simple example without caring for best practices or do I just > not know better? With a default filter the first example is simply wrong. Without a default filter the second example is simply wrong. I don't however think we should be censoring these kinds of things. Possibly because I don't consider the notes as a copy&pastable library... -Hannes