Fantastic points! Request for a bunch more, written up.
http://www.sinatrarb.com/ at least does it with one file (but it's not HTML, which I agree is a lower on-ramp).
User comments on docs is brilliant. Flash does this, but moderated, with a long delay (weeks!). So, a reddit/digg/HN/SO voting scheme would fix this. But I agree, that just plain comment - unvoted, unmoderated - would still be a net win.
Javadocs is assisted by strong typing. A huge win is hyperlinks for return types and arguments, so you can quickly trace through. A doc-only type-system convention for python would help here. There's also that extreme approach in Haskell of looking up functions entirely by their type signatures.
"Let it crash" is cool, but makes sense only for servers, I think. It's moving away from a general purpose language to a specific application. But it's an important one, so why not? I mention this just because it's a bit mind-twisting.
EDIT doctest was new to me, and that's fantastic too. http://docs.python.org/library/doctest.html Years ago, I had the idea of writing unit tests automatically, by capturing the output of a manual test session, and then using it directly as an automated test: so that you get it 100% for free, since you do the work anyway. I didn't realize that python's REPL makes this trivial (uh... so lisp has probably been doing this for 30 years...); and pasting it in the code itself is another cool improvement. It still has the problem of unit tests, of freezing the API; but if you change it, you'll want to test it again anyway. Hey, if you refactor the code, you can probably refactor the REPL session at the same time.
http://www.sinatrarb.com/ at least does it with one file (but it's not HTML, which I agree is a lower on-ramp).
User comments on docs is brilliant. Flash does this, but moderated, with a long delay (weeks!). So, a reddit/digg/HN/SO voting scheme would fix this. But I agree, that just plain comment - unvoted, unmoderated - would still be a net win.
Javadocs is assisted by strong typing. A huge win is hyperlinks for return types and arguments, so you can quickly trace through. A doc-only type-system convention for python would help here. There's also that extreme approach in Haskell of looking up functions entirely by their type signatures.
"Let it crash" is cool, but makes sense only for servers, I think. It's moving away from a general purpose language to a specific application. But it's an important one, so why not? I mention this just because it's a bit mind-twisting.
EDIT doctest was new to me, and that's fantastic too. http://docs.python.org/library/doctest.html Years ago, I had the idea of writing unit tests automatically, by capturing the output of a manual test session, and then using it directly as an automated test: so that you get it 100% for free, since you do the work anyway. I didn't realize that python's REPL makes this trivial (uh... so lisp has probably been doing this for 30 years...); and pasting it in the code itself is another cool improvement. It still has the problem of unit tests, of freezing the API; but if you change it, you'll want to test it again anyway. Hey, if you refactor the code, you can probably refactor the REPL session at the same time.
As I said: fantastic, request for a bunch more.