Comment by stronglikedan

To me, you're describing a specification, a type of documentation, with examples being another type. And I agree that a specification should just list definitions with explanations.

But there's no reason that a document cannot contain both a specification and examples. That's the type I prefer, and that's the type I mostly encounter nowadays. Usually a specification on the left with some examples on the right, maybe even interactive examples.