[tomashm]

tldr; Adding key examples to a specification makes it much easier to understand.

I learned programming with Pascal at university. It had a very formal, math-like syntax, complete with BNF-style grammar.

The next course used the famous K&R book (The C Programming Language), and what a breeze that was! It taught by showing lots of relevant, working examples.

Since then, I’ve realized that while examples aren’t a substitute for a clear specification, well-chosen examples make specs far easier to grasp.

I recommend reading Gojko Adzic’s thoughts on this (https://www.linkedin.com/in/gojko/). He’s the author of Specification by Example.

He argues that identifying and refining key examples is a great way to raise the quality of documentation and shared understanding.