[mti]

> I'm of the opinion that worked examples are often worse than no documentation.

That's completely baffling to me so I'd be really curious to hear your reasons (or those of someone who shares that opinion, as there are others in the thread apparently).

When learning about an abstract notion, it has been my experience that having good examples in mind (in the sense that they are not too complex, but non-trivial enough to illustrate the relevant aspect of the notion at hand) is very helpful, if not essential, for comprehension. All the more so for very abstract subjects (e.g. back in grad school I was studying algebraic geometry, and you can't go very far in that subject trying to prove things about functors on the category of rings without examples in mind that connect the abstract nonsense to some actual geometric meaning).

Speaking of abstract nonsense, by the way, under the Curry-Howard isomorphism, publishing a library with type signatures but no worked out example is equivalent to publishing a mathematical paper consisting entirely of lemmas with no example of how to combine them to prove something interesting (in fact, it's worse, because the expressiveness of the Haskell type system obviously pales in comparison to the language of mathematical papers). I would almost certainly reject a paper like that if I received one for review, and I expect most referees would too.