Developing New ACE+TAO Tutorials

Here are some general guidelines for creating new ACE+TAO tutorials:


Choose a Topic You Know Very Well (or are just learning)

This isn't really a conflict...

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.


Keep It Simple

Don't try to use a lot of really cool ACE+TAO features along the way. Stick to the basic stuff and show that. Try to use a minimum of ACE+TAO objects that are not the direct target of the tutorial.

(For instance, don't get all caught up in ACE_Singleton<> if you're trying to show how to use an ACE_Reactor.)

If you want to show something really cool that happens to depend on another ACE+TAO 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.


Document the Heck Out of It!

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.

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.


Over-teach It

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.


Leverage Existing Code

The ultimate form of code reuse :-) Seriously... grab one or more of the existing ACE+TAO 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!

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...


Back to the ACE tutorials or TAO tutorials page.