Comments on: Entertaining Documentation http://jessenoller.com/2008/08/28/entertaining-documentation/ python, programming and other things Thu, 11 Feb 2010 00:42:02 +0000 http://wordpress.org/?v=2.9.2 hourly 1 By: tag http://jessenoller.com/2008/08/28/entertaining-documentation/comment-page-1/#comment-139634 tag Sun, 31 Aug 2008 13:46:33 +0000 http://jessenoller.com/?p=295#comment-139634 Robert, I've heard this complaint <a href="http://simonwillison.net/2008/Apr/2/pythonbyexample/" rel="nofollow">before</a>. A couple of alternative references may help:<br><br><a href="http://pbe.lightbird.net/" rel="nofollow">http://pbe.lightbird.net/</a><br><a href="http://effbot.org/zone/librarybook-index.htm" rel="nofollow">http://effbot.org/zone/librarybook-index.htm</a><br><br>I also think that online reference documentation can easily incorporate examples and discussion, without becoming flabby: just link to it, or have some Javascript fold it away.<br><br>As it happens, I don't really suffer from any lack of examples. Whenever I'm writing Python I have an interpreted session running, and I just try the code out, so I'm learning by doing which is always the best way. Robert, I've heard this complaint before. A couple of alternative references may help:

http://pbe.lightbird.net/
http://effbot.org/zone/librarybook-index.htm

I also think that online reference documentation can easily incorporate examples and discussion, without becoming flabby: just link to it, or have some Javascript fold it away.

As it happens, I don't really suffer from any lack of examples. Whenever I'm writing Python I have an interpreted session running, and I just try the code out, so I'm learning by doing which is always the best way.

]]> By: tag http://jessenoller.com/2008/08/28/entertaining-documentation/comment-page-1/#comment-62114 tag Sun, 31 Aug 2008 09:46:33 +0000 http://jessenoller.com/?p=295#comment-62114 Robert, I've heard this complaint <a href="http://simonwillison.net/2008/Apr/2/pythonbyexample/" rel="nofollow">before</a>. A couple of alternative references may help:<br><br><a href="http://pbe.lightbird.net/" rel="nofollow">http://pbe.lightbird.net/</a><br><a href="http://effbot.org/zone/librarybook-index.htm" rel="nofollow">http://effbot.org/zone/librarybook-index.htm</a><br><br>I also think that online reference documentation can easily incorporate examples and discussion, without becoming flabby: just link to it, or have some Javascript fold it away.<br><br>As it happens, I don't really suffer from any lack of examples. Whenever I'm writing Python I have an interpreted session running, and I just try the code out, so I'm learning by doing which is always the best way. Robert, I've heard this complaint before. A couple of alternative references may help:

http://pbe.lightbird.net/
http://effbot.org/zone/librarybook-index.htm

I also think that online reference documentation can easily incorporate examples and discussion, without becoming flabby: just link to it, or have some Javascript fold it away.

As it happens, I don't really suffer from any lack of examples. Whenever I'm writing Python I have an interpreted session running, and I just try the code out, so I'm learning by doing which is always the best way.

]]> By: Robert http://jessenoller.com/2008/08/28/entertaining-documentation/comment-page-1/#comment-62113 Robert Fri, 29 Aug 2008 16:20:16 +0000 http://jessenoller.com/?p=295#comment-62113 I have always lamented the docs not having more examples. It could be my short coming in reading what is there and translating that to code...but I would like them anyway. I have always lamented the docs not having more examples. It could be my short coming in reading what is there and translating that to code…but I would like them anyway.

]]> By: Ben http://jessenoller.com/2008/08/28/entertaining-documentation/comment-page-1/#comment-62115 Ben Fri, 29 Aug 2008 01:17:48 +0000 http://jessenoller.com/?p=295#comment-62115 I don't really care about humor in my documentation, I just want to find out what I need to know from it. In code comments, that's a different story... A random joke here and there really breaks up the tedium of learning or reviewing code. I don't really care about humor in my documentation, I just want to find out what I need to know from it. In code comments, that's a different story… A random joke here and there really breaks up the tedium of learning or reviewing code.

]]> By: jnoller http://jessenoller.com/2008/08/28/entertaining-documentation/comment-page-1/#comment-62112 jnoller Thu, 28 Aug 2008 16:03:39 +0000 http://jessenoller.com/?p=295#comment-62112 Agreed. I can't echo "lots of examples" enough Agreed. I can't echo “lots of examples” enough

]]> By: anon http://jessenoller.com/2008/08/28/entertaining-documentation/comment-page-1/#comment-62111 anon Thu, 28 Aug 2008 14:46:34 +0000 http://jessenoller.com/?p=295#comment-62111 just give me clear and understandable docs with lots of examples. When I wanna laugh, I'll go to the movies :) just give me clear and understandable docs with lots of examples. When I wanna laugh, I'll go to the movies :)

]]>