tomee-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dblev...@apache.org
Subject svn commit: r1195804 - /openejb/site/trunk/content/dev/writing-examples.mdtext
Date Tue, 01 Nov 2011 03:59:03 GMT
Author: dblevins
Date: Tue Nov  1 03:59:02 2011
New Revision: 1195804

URL: http://svn.apache.org/viewvc?rev=1195804&view=rev
Log:
description of how to write good examples

Added:
    openejb/site/trunk/content/dev/writing-examples.mdtext

Added: openejb/site/trunk/content/dev/writing-examples.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/dev/writing-examples.mdtext?rev=1195804&view=auto
==============================================================================
--- openejb/site/trunk/content/dev/writing-examples.mdtext (added)
+++ openejb/site/trunk/content/dev/writing-examples.mdtext Tue Nov  1 03:59:02 2011
@@ -0,0 +1,87 @@
+Title: Writing Examples
+
+Some basic guideliness of writing examples:
+
+ - focus on one idea per example
+ - keep examples short
+    - one test case
+    - minimal code to make the point
+ - avoid showing an entire API in one example, if possible
+ - be concious of the cost of "setting the stage"
+ - if examples get too big, split it
+
+# Noise vs signal
+
+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.
+
+# 5 was to do the same thing
+
+It takes time to learn the example scenario.  Be very mindful of that.
+
+If there are five ways to do the same thing, avoid making 5 different 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 concecpt.  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.
+
+Which is easier to learn?
+
+ - 934 + 55 = 989
+ - 513 - 19 = 494
+ - 468 * 44 = 20592
+ - 708 / 89 = 7
+ - 401 % 63 = 23
+
+Or:
+
+ - 102 + 35 = 137
+ - 102 - 35 = 67
+ - 102 * 35 = 3570
+ - 102 / 35 = 2
+ - 102 % 35 = 32
+
+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.
+
+# Short Class Names
+
+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:
+
+ - `BeanWithTwoDecoratorsAndOneProducerMethod`
+
+Try instead:
+
+ - `BlueBean`
+
+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?
+
+ - 102 + 35 = 137
+ - 102 - 35 = 67
+ - 102 * 35 = 3570
+ - 102 / 35 = 2
+ - 102 % 35 = 32
+
+Or:
+
+ - 12 + 3 = 15
+ - 12 - 3 = 9
+ - 12 * 3 = 36
+ - 12 / 3 = 4
+ - 12 % 3 = 0
+
+There's a finite amount people can keep in their head, save space for the important stuff.
+



Mime
View raw message