Writing an example is easy. Any example is a good one. The more the better.
Writing examples that can be used in a presentations is hard.
Some basic guidelines of writing 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
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
Avoid that. Copy
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.
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?
There's a finite amount people can keep in their head, save space for the important stuff.
All edits are reviewed before going live, so feel free to do much more than fix typos or links. If you see a page that could benefit from an entire rewrite, we'd be thrilled to review it. Don't be surprised if we like it so much we ask you for help with other pages :)NOTICE: unless indicated otherwise on the pages in question, all editable content available from apache.org is presumed to be licensed under the Apache License (AL) version 2.0 and hence all submissions to apache.org treated as formal Contributions under the license terms.