Writing Presentable Examples

It takes time to learn the example scenario (noise). You need to learn the scenario before you can start to see the important parts (signal).

Be very mindful of your noise to signal ratio.

Example scenarios do not need to be believable and should not be elaborate. Get to the point in as few classes as possible.

You should be able to explain the entire example in two minutes.

If there are five ways to do the same thing, avoid making five different scenarios. Copy the example to a new directory, and tweak it to show the variation.

So say you used objects Green, Square and Checkers to show the basic concept and you wish to show the next variation of that same concept. It is tempting to add to the same example objects Yellow, Triangle and PolkaDots.

Avoid that. Copy Green, Square and Checkers to a new example, change the package name, and update the few lines needed to show the difference.

Where does your eye focus?

How about now?

The intent of the second set of numbers can be easily guessed. An explanation that it is about the math operators confirms that and locks it in your brain.

When presenting, you only get so much time to show people ideas. If they have to learn a new set of names and understand their relationship on each tiny variation, it severely impacts their ability to see what is supposed to be the same and what is supposed to be different. As a presenter this means you must show less and what you do show will be shown less clearly.

When names and scenarios are consistent, the variations jump out quickly and with impact.

If there are five ways to do the same thing, show the same thing five different ways.

You don’t need to document the example with the class name. Class names that are a mouthful cannot be effectively used in presentations or screencasts.

Try to stick with one or two word class names. Three tops.

Avoid:

Try instead:

Shorter names can be easier for all sorts of reasons. Less words to keep "floating in the head" when trying to truly see an example.

Using the numbers from the previous section, which is easier?

Or:

There’s a finite amount people can keep in their head, save space for the important stuff.