blob: af3846b7af779d11aed3b9166fbfddca18f07a3d (
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
73
74
75
76
77
78
79
80
|
<TITLE>ACE Beginners' Guide</TITLE>
<BODY text = "#000000" link="#000fff" vlink="#ff0f0f" bgcolor="#ffffff">
<HR><P>
<H3>Developing New Tutorials</H3>
Here are some general guidelines for creating new ACE tutorials: <P>
<hr width=50% align=left>
<H4>Choose a Topic You Know Very Well (or are just learning)</h4>
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>
<hr width=50% align=left>
<H4> Keep It Simple</H4>
<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>
<hr width=50% align=left>
<h4>Document the Heck Out of It!</H4>
<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>
<hr width=50% align=left>
<h4>Over-teach It</H4>
<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>
<hr width=50% align=left>
<h4>Leverage Existing Code</H4>
<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!
<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>
<HR><P> <H3> What about TAO?</H3> In the early stages, these tutorials
won't address The ACE ORB (<A
HREF="http://www.cs.wustl.edu/~schmidt">TAO</A>). However, if you
want to request a tutorial on some aspect of TAO or even create one
yourself, I'll be glad to integrate those into these tutorials. It's
rare when folks want to write documentation, so nothing will be
refused!<P>
<HR><P>
Back to the <A
HREF="../ACE-tutorials.html">ACE
tutorials</A> page.
|
