CyberTech Rambler

August 14, 2009

How to write a useful (and useable) tutorial

Filed under: Uncategorized — ctrambler @ 8:04 pm

By way of Rob Weir blog post, I found an excellent beginner’s text for ODF by J. David Eisenberg.

Why do I call it an excellent tutorial? First of all, it start from the very beginning: The first tutorial show you how to create a really simple and basic ODF document with one paragraph (and one image). That is a extremely important starting point for beginners. Let’s face it, we all have to start there. One advantage of starting from there is, if you manage to compile and create the document, you know you can always start from here for your document (or go back to here and start again). Moreover, even season programmers do not necessary will be able to compile the program correctly on the first run. By presenting a bare-bone program, all you and I has to do is to concentrate on getting the program compile. We are not distracted by syntax or other issue.

Second, the tutorial does not advocate any technology.  With this, I mean one do not have to learn a lot of surrounding technology to get oneself started. The first few tutorial only requires you to know DOM. To me that is something most people with XML experience will know how to use. Without it, you cannot manipulate any complex XML beyond the simple one you created yourself.  Even if you do not know how to use DOM, the DOM syntax is written in the way developers are trained in, so it will still be easy to follow.

What are the alternative approaches? One way is to lean very heavily on what the toolkit offer, i.e., go away from the bare metal feel and start relying on toolkit. This is the way the OOXML camp choose to introducte OOXML. Compare tutorial one, two, three and four here with Rajabi’s OOXML tutorial number one, two, four and three (I swapped four and three to keep the comparison valid) respectively on Brian Jone’s blog, remember to strip away all programming language specific fluff and concentrate on the content only, i.e., how to create documents.  Now tell me, which one tell you more about the document technology itself, and which one tell you more about the toolkit and has the effect of hiding the technology from you? Which give you more confidence to proceed to experiment about the toolkit by messing around with  the tutorial materials. Also tell me which one is easier to follow and understand.

That is not to  say Rajabi took the wrong approach. The approach he took requires you to put all your faith in the toolkit but allow you to scale up really quickly to do something interesting. Nobody in their right mind will write ODF as raw XML, and sooner or later Eisenberg will have to move away from bare metal XML and start showing us how the tookit simplify creating and manipulating XML the way Rajabi introduces OOXML. The way one eventually use ODF will be through the equivalent fluffy functions in ODF toolkit.

I prefer building a strong foundation on the document technology and Eisenberg does it. I believe that Rajabi approach has a fatal flaw: The speed of scaling up comes at a very high price: You have not learned about the document technology so  if something goes wrong, you cannot tell what is wrong. It’s like building a house without a solid foundation. Without the foundation, you are going to spend more time figuring out what went wrong later, and will find it difficult to switch toolkit because you are afraid that you have to relearn everything from scratch again. For these reason, I believe this approach is not for beginners.

In defense of Rajabi, if you look at the books published by Microsoft Press, you will find that Rajabi’s approach is the standard Microsoft approach to teaching technology.


Leave a Comment »

No comments yet.

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Create a free website or blog at

%d bloggers like this: