Right size examples?

Nothing illustrates a point as well as a good example. Sometimes even a mediocre example illustrates a point better than several paragraphs of text.

Sample code

Trouble comes when the example is not complete enough to test automatically. One change in naming can make the code silently out of date.

Trouble also arises when the example is so realistic that an untrained eye cannot determine which trees are important in the forest of information.

The example above is too short to compile, but still full of extra information that could distract a reader from the essential points of getting a connection from the factory, binding as Babs Jensen, and finally closing the connection.

How have you solved this problem in your docs?