blob: c10c84d45d73de369486a261e182dd273c76aa77 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Writing Presentable Examples</title>
<meta name="description" content="Apache TomEE">
<meta name="author" content="Apache TomEE">
<meta name="google-translate-customization" content="f36a520c08f4c9-0a04e86a9c075ce9-g265f3196f697cf8f-10">
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Expires" content="0">
<meta http-equiv="Cache-Control" content="no-store, no-cache, must-revalidate, max-age=0">
<!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<!-- Le styles -->
<link href="./../resources/css/bootstrap.css" rel="stylesheet">
<link href="./../resources/css/prettify.css" rel="stylesheet">
<!--link href="./../resources/css/bootstrap-mods.css" rel="stylesheet"-->
<link href="./../resources/css/main.css" rel="stylesheet">
<link href="./../resources/font-awesome-4.6.3/css/font-awesome.min.css" rel="stylesheet">
<script type="text/javascript">
var t = encodeURIComponent(document.title.replace(/^\s+|\s+$/g,""));
var u = encodeURIComponent(""+document.URL);
function fbshare () {
window.open(
"http://www.facebook.com/sharer/sharer.php?u="+u,
'Share on Facebook',
'width=640,height=426');
};
function gpshare () {
window.open(
"https://plus.google.com/share?url="+u,
'Share on Google+',
'width=584,height=385');
};
function twshare () {
window.open(
"https://twitter.com/intent/tweet?url="+u+"&text="+t,
'Share on Twitter',
'width=800,height=526');
};
function pinshare () {
window.open("//www.pinterest.com/pin/create/button/?url="+u+"&media=http%3A%2F%2Ftomee.apache.org%2Fresources%2Fimages%2Ffeather-logo.png&description="+t,
'Share on Pinterest',
'width=800,height=526');
};
</script>
<!-- Le fav and touch icons -->
<link rel="shortcut icon" href="./../favicon.ico">
<link rel="apple-touch-icon" href="./../resources/images/apple-touch-icon.png">
<link rel="apple-touch-icon" sizes="72x72" href="./../resources/images/apple-touch-icon-72x72.png">
<link rel="apple-touch-icon" sizes="114x114" href="./../resources/images/apple-touch-icon-114x114.png">
<script src="./../resources/js/prettify.js" type="text/javascript"></script>
<script src="./../resources/js/jquery-latest.js"></script>
<script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script>
<script src="./../resources/js/common.js"></script>
<script src="./../resources/js/prettyprint.js"></script>
<!--script src="//assets.pinterest.com/js/pinit.js" type="text/javascript" async></script//-->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-2717626-1']);
_gaq.push(['_setDomainName', 'apache.org']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div class="topbar" data-dropdown="dropdown">
<div class="fill">
<div class="container">
<a class="brand" href="./../index.html">Apache TomEE</a>
<ul class="nav">
<li class="dropdown">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">
Apache
<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<!-- <li><a href="./../misc/whoweare.html">Who we are?</a></li> -->
<!-- <li><a href="./../misc/heritage.html">Heritage</a></li> -->
<li><a href="http://www.apache.org">Apache Home</a></li>
<!-- <li><a href="./../misc/resources.html">Resources</a></li> -->
<li><a href="./../misc/contact.html">Contact</a></li>
<li><a href="./../misc/legal.html">Legal</a></li>
<li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
<li class="divider"/>
<li><a href="http://www.apache.org/security">Security</a></li>
</ul>
</li>
<li><a href="./../index.html">Home</a></li>
<li><a href="./../downloads.html">Downloads</a></li>
<li><a href="./../documentation.html">Documentation</a></li>
<li><a href="./../examples-trunk/index.html">Examples</a></li>
<li><a href="./../support.html">Support</a></li>
<li><a href="./../contribute.html">Contribute</a></li>
<li><a href="./../security/index.html">Security</a></li>
</ul>
<!-- Google CSE Search Box Begins -->
<FORM class="pull-right" id="searchbox_010475492895890475512:_t4iqjrgx90" action="http://www.google.com/cse">
<INPUT type="hidden" name="cx" value="010475492895890475512:_t4iqjrgx90">
<INPUT type="hidden" name="cof" value="FORID:0">
<INPUT size="18" width="130" style="width:130px" name="q" type="text" placeholder="Search">
</FORM>
<!--<SCRIPT type="text/javascript" src="http://www.google.com/coop/cse/brand?form=searchbox_010475492895890475512:_t4iqjrgx90"></SCRIPT>-->
<!-- Google CSE Search Box Ends -->
</div>
</div>
</div>
<div class="container">
<div class="page-header">
<small><a href="./../index.html">Home</a>&nbsp;&raquo&nbsp;<a href="./../dev/">Dev</a></small><br>
<h1>Writing Presentable Examples
<div style="float: right; position: relative; bottom: -10px; ">
<a onclick="javascript:gpshare()" class="gp-share sprite" title="Share on Google+">share [gp]</a>
<a onclick="javascript:fbshare()" class="fb-share sprite" title="Share on Facebook">share [fb]</a>
<a onclick="javascript:twshare()" class="tw-share sprite" title="Share on Twitter">share [tw]</a>
<a onclick="javascript:pinshare()" class="pin-share sprite" title="Share on Pinterest">share [pin]</a>
<a data-toggle="modal" href="#edit" class="edit-page" title="Contribute to this Page">contribute</a>
</div>
</h1>
</div>
<p>Writing an example is easy. Any example is a good one. The more the better.</p>
<p>Writing examples that can be used in a presentations is hard.</p>
<p>Some basic guidelines of writing examples:</p>
<ul>
<li>focus on one idea per example</li>
<li>keep examples short
<ul>
<li>one test case</li>
<li>minimal code to make the point</li>
</ul></li>
<li>avoid showing an entire API in one example, if possible</li>
<li>be conscious of the cost of "setting the stage"</li>
<li>if examples get too big, split it</li>
</ul>
<h1>Noise vs signal</h1>
<p>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).</p>
<p>Be very mindful of your noise to signal ratio.</p>
<p>Example scenarios do not need to be believable and should not be elaborate. Get to the point in as few classes as possible.</p>
<p>You should be able to explain the entire example in two minutes.</p>
<h1>Five ways to do the same thing</h1>
<p>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.</p>
<p>So say you used objects <code>Green</code>, <code>Square</code> and <code>Checkers</code> 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 <code>Yellow</code>, <code>Triangle</code> and <code>PolkaDots</code>.</p>
<p>Avoid that. Copy <code>Green</code>, <code>Square</code> and <code>Checkers</code> to a new example, change the package name, and update the few lines needed to show the difference.</p>
<p>Where does your eye focus?</p>
<ul>
<li>934 + 55 = 989</li>
<li>513 - 19 = 494</li>
<li>468 * 44 = 20592</li>
<li>708 / 89 = 7</li>
<li>401 % 63 = 23</li>
</ul>
<p>How about now?</p>
<ul>
<li>102 + 35 = 137</li>
<li>102 - 35 = 67</li>
<li>102 * 35 = 3570</li>
<li>102 / 35 = 2</li>
<li>102 % 35 = 32</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>When names and scenarios are consistent, the variations jump out quickly and with impact.</p>
<p>If there are five ways to do the same thing, show the same thing five different ways.</p>
<h1>Short Class Names</h1>
<p>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.</p>
<p>Try to stick with one or two word class names. Three tops.</p>
<p>Avoid:</p>
<ul>
<li><code>BeanWithTwoDecoratorsAndOneProducerMethod</code></li>
</ul>
<p>Try instead:</p>
<ul>
<li><code>BlueBean</code></li>
</ul>
<p>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.</p>
<p>Using the numbers from the previous section, which is easier?</p>
<ul>
<li>102 + 35 = 137</li>
<li>102 - 35 = 67</li>
<li>102 * 35 = 3570</li>
<li>102 / 35 = 2</li>
<li>102 % 35 = 32</li>
</ul>
<p>Or:</p>
<ul>
<li>12 + 3 = 15</li>
<li>12 - 3 = 9</li>
<li>12 * 3 = 36</li>
<li>12 / 3 = 4</li>
<li>12 % 3 = 0</li>
</ul>
<p>There's a finite amount people can keep in their head, save space for the important stuff.</p>
<div id="edit" class="modal hide fade in" style="display: none; ">
<div class="modal-header">
<a class="close" data-dismiss="modal">x</a>
<h3>Thank you for contributing to the documentation!</h3>
</div>
<div class="modal-body">
<h4>Any help with the documentation is greatly appreciated.</h4>
<p>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 :)</p>
<small>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.</small>
<!--[if gt IE 6]>
<h4>Internet Explorer Users</h4>
<p>If you are not an Apache committer, click the Yes link and enter a <i>anonymous</i> for the username and leave the password empty</p>
<![endif]-->
</div>
<div class="modal-footer">
Do you have an Apache ID?
<a href="javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))" class="btn">Yes</a>
<a href="javascript:void(location.href='https://anonymous:@cms.apache.org/redirect?uri='+escape(location.href))" class="btn">No</a>
</div>
</div>
<script src="./../resources/js/bootstrap-modal.js"></script>
<footer>
<p>Copyright &copy; 1999-2016 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation.
All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>
</footer>
</div> <!-- /container -->
<!-- Javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="./../resources/js/bootstrap-dropdown.js"></script>
</body>
</html>