Developing New Tutorials

Here are some general guidelines for creating new ACE 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 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.

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

What about TAO?

In the early stages, these tutorials won't address The ACE ORB (TAO). 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!

Back to the ACE tutorials page.