<div class="gmail_quote">On Sat, Aug 6, 2011 at 03:08, Danny Yoo <span dir="ltr"><<a href="mailto:dyoo@cs.wpi.edu">dyoo@cs.wpi.edu</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
I'm thinking of writing a series called "Racket Slices", which does a<br>
cookbook-style approach to learning about Racket. I think there's a<br>
need for documentation that takes a "slice", a cross section of Racket<br>
to do some simple (but real-world!) task. And since we're using the<br>
name "Racket", it demands that we use a pun about tennis.<br>
<br>
Here's what I'm thinking of:<br>
<br>
<a href="http://hashcollision.org/racket-slices/irc-parsing/index.html" target="_blank">http://hashcollision.org/racket-slices/irc-parsing/index.html</a><br>
<br>
<br>
How does it look?<br></blockquote><div><br></div><div><br></div><div>Good work! If feels easy to read. Maybe you'll come up with more "revisions" just like it happened to the brainfudge #lang tutorial.</div>
<div><br></div><div>I believe the "series" would be valuable for the community.</div><div><br></div><div><br></div><div><br></div><div>Today I came across the following excerpt which highlights the importance of having examples to learn from:</div>
<div><br></div><blockquote class="gmail_quote" style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0.8ex; border-left-width: 1px; border-left-color: rgb(204, 204, 204); border-left-style: solid; padding-left: 1ex; ">
<span class="Apple-style-span" style="font-family: Quattrocento, serif; font-size: 16px; "><strong>Examples</strong> over <strong>Documentation</strong>: Attempts to use components were helped not by documentation but by the availability of example code that could be copy-and-pasted into the application and then tweaked to fit the situation. In some cases documentation was actually a hindrance. Misleading documentation found through Google led one team down a blind alley trying to use an inappropriate library that didn't actually do what was required. Another team tried to use a component that had huge amounts of well written documentation that was entirely useless and so slowed them down because they had to wade through a lot of text before finding out that they were wasting time. A team using components that had been developed test-first found the tests to be useful both as documentation and a good source of example code.</span></blockquote>
</div><br><div><br></div><div>from <a href="http://www.natpryce.com/articles/000555.html">http://www.natpryce.com/articles/000555.html</a></div><div><br></div><div><br></div><div>So having more examples of Racket code around can be a good thing when people need to find out how to use certain functions, etc.</div>
<div><br></div><div>[]'s</div><div><br></div><div>Rodolfo</div>