Comment by voidhorse

Examples are indeed crucial, but conceptual documentation and contract documentation that describes behaviors that cannot be formally made transparent in the language are equally important, and often missing too. In fact, I'd argue they are more important because an example can be easily misunderstood without this surrounding context.