summaryrefslogtreecommitdiff
path: root/etc/ACE-tutorials.html
blob: f8685bea71ab9e1f5dc38be4db50a952a267847e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
<TITLE>ACE Beginners' Guide</TITLE>
<BODY text = "#000000" link="#000fff" vlink="#ff0f0f" bgcolor="#ffffff">

<CENTER><H1>The Beginners' Guide to ACE</H1></CENTER>
<P>

This site is dedicated to developing a set of tutorials to get ACE
newcomers up to speed with the framework.  For now, this will be
limited strictly to ACE matters but I'm not opposed to setting up a
separate area for TAO.  In fact, I encourage it!  <P>

Here are some general guidelines for creating tutorials:
<P>
<UL>
<LI> Choose a topic that you know very well or are just learning.
<P>
  This isn't really a conflict...
<P>
  If you know a topic very well, you're likely to know what is most
  important to the novice and what can be left until later.  If you're
  just learning a topic, then you know what questions you have that
  must be answered before you can continue.
<P>
<LI> Keep it simple.
<P>
  Don't try to use a lot of really cool ACE features along the way.  Stick
  to the basic stuff and show that.  Try to use a minimum of ACE objects
  that are not the direct target of the tutorial.
<P>
  (For instance, don't get all caught up in ACE_Singleton<> if you're
   trying to show how to use an ACE_Reactor.)
<P>
  If you want to show something really cool that happens to depend on 
  another ACE feature, do a tutorial on that other feature first!  I've
  found that folks will tend to get stuck on *anything* they don't
  understand even if it isn't directly relevant to what you're trying
  to teach.
<P>
<LI> Document the heck out of it!
<P>
  There's no such thing as too much documentation.  Don't worry about
  repeating yourself along the way.  Assume that the reader knows nothing
  at all about the topic at hand and explain even the parts that you feel
  are painfully obvious.
<P>
  If you feel that sticking a bunch of comments in the code makes it harder
  to read then stick in a label and document at the end of the file or
  something.  Alternately, create both a well-documented version and a
  sparsely-documented version.  Then folks can choose between 'em.
<P>
<LI> Over-teach it.
<P>
  If there's a tutorial created for a topic that you feel strong in,
  create another one anyway.  Everybody tends to code a little differently.
  Perhaps your tutorial style will "feel" better to some newcomers
  than an existing tutorial.  You won't hurt anybody's feelings if
  you present the same material in a different way.
<P>
<LI> Steal existing code.
<P>
  The ultimate form of code reuse :-)  Seriously...  grab one or more
  of the existing ACE tests or examples.  Then strip it down to the
  bare bones & add heaps of comments.  I don't think the software-police
  will be coming after anyone for that!
</UL>
<P>
If this thing takes off, I'll start to organize the tutorials into
groups.  For now, lets concentrate on quantity & quality.  Organization
can come later...
<P>
<A HREF="tutorials">Follow this link to the tutorials...</A>