It's an interesting approach, and might make you more inclined to write documentation -- as it is less hassle to do so. But the end result isn't very readable,

It's an interesting approach, and might make you more inclined to write documentation -- as it is less hassle to do so. But the end result isn't very readable, the text ends up being an API reference disguised as something else. I prefer a "literate testing" approach, where you mix documentation with doctests. It's easier to tell a story when you show the reader what your API does, instead of its internals. And you will never have to worry about keeping the examples up-to-date with your code if you make them doctests.