I read lots articles, tutorials and whitepapers whenever I get the chance. Sometimes I’ll read something and feel enlightened. Other times I finish and feel that I’ve somehow lost brain cells (please, no jokes about having none to lose 
). Recently some of the tutorials I’ve read on the web have left me feeling extremely underwhelmed. The reasons are because I felt like I didn’t learn anything or that the tutorial, while hitting the point, didn’t actually feel like it delivered the kind of information I was expecting. Since going through a few experiences like this I have started to wonder what really makes up a good tutorial, and how does it differ from a ‘how-to’ or a whitepaper?
I think that my definition of a tutorial is slightly different from the “official” definition, and the one that most other people use. So, here is the obligatory official definition 
(from Dictionary.com):
Tutorial - tu·to·ri·al … [too-tawr-ee-uhl, -tohr-, tyoo-] …
- pertaining to or exercised by a tutor: tutorial functions or authority.
- a class in which a tutor gives intensive instruction in some subject to an individual student or a small group of students.
- Computers
- programmed instruction provided to a user at a computer terminal, often concerning the use of a particular software package and built into that package.
- a manual explaining how to use a particular software package or computer system.
Yup, just as I suspected.
OK, a bit of background information. In many fields a tutorial can be a basic step-by-step to doing something - that I’m OK with. But I think that there are some areas of my chosen field (that’d be geekness) where a simple step-by-step just doesn’t cut it. A really good example of this would be my solution/tutorial that I previously blogged about. Regardless of who you are, reading a simple tutorial on this topic would show you how to do it, but it wouldn’t in any way give you the reasons for the steps involved. Now, this solution of mine doesn’t give a complete set of background information required to understand every step, but it does explain areas that are specific to this problem (along with a few extra snippets to help people learn stuff). So some background knowledge is required, and I think that’s the big proviso about tutorials - background knowledge.
I try to write my tutorials in such a way that the amount of background knowledge required is minimal without completely modifying the scope of the tutorial. For example, if I were to write a tutorial on polymorphism, I would expect people to have some knowledge of object orientation and some skills with any form of programming language. Me being me, I’d probably use C++ for my examples, so some understanding of the language and it’s syntax would also be required. I may, during the course of the tutorial, discuss some issues that aren’t directly related to the understanding of polymorphism (such as pointer sizes and vtables), as I might feel that it aids in understanding more of the world that polymorphism lives in. It’s this kind of information that is lacking in most tutorials.
This post was actually inspired by a couple of video tutorials that I watched recently which was designed to show you how to unpack a packed executable, using a few of handy tools (such as a debugger, disassembler and PE explorers). Now, the tutorial (which I’m not going to link to for fear of pissing off the author!) really cut to the chase. It basically went…
Run that, press that, copy that, press that, run that, run this, press that, run that, and you’re done! Congrats you can now unpack exes packed with X.
Hardly inspiring. I wondered if the quality of the tutorials was consistant, so I watched another one - again it was on unpacking, but this time it was a different packing algorithm. It was almost exactly the same, the only apparent differences were the names of the exes that were packed, a few memory addresses, and the disassembled code that was visible in the debugger.
This particular individual has uploaded dozens of these tutorials for the world to view, and I really think he/she believes they’re extremely productive. I can’t help but think that they’re not - they could write a single tutorial that covers the theory of unpacking, with one or two examples, and the reader/viewer would actually learn the principles and techniques behind unpacking, rather than just watching someone else press a few buttons in a certain order. I don’t expect a full run down on what a debugger is, or what reverse engineering is all about, but at least discussing how the packing process works, and why certain steps are taken to unpack the executable would be a very good, and helpful, move. I feel that anything less that this is half-assed!
So, in my world of geekness, a valuable tutorial needs to be more than what the dictionary says a tutorial should be. In my opinion, it should give you the required knowledge to understand what the tutorial is demonstrating and it should be delivered in such a way that allows the viewer to find it easy to understand the examples along with providing information on how to get access to extra information which may aid in their understanding. The feedback I’ve had from my previous reverse engineering solution has been great, and it seems that I’ve covered things in just enough detail to allow people to understand - this may well have been the first time I’ve achieved it.
Now I realise that some of you may jump on my back and yell “Why don’t you practice what you preach!?”, and you’d be quite within your rights to do that For your information, I intend to do just that. I will be writing some tutorials and lessons on various topics in the coming weeks, and I will be doing my best to cover the subject in as much detail as possible without changing the scope of the work.
April 16, 2007
I agree up to a point, BUT, perhaps I have a different viewpoint as my fiancée is an experienced technical author/trainer.
One of the golden rules of any training (especially when someone is totally new to the subject) is not to overload people with background information, because if people are trying to hold too much in working memory they simply don’t take of it in.
You polymorphism example is a good one. If you’d never heard of it before, it may be better to explain the concept first and later do a practical C++ tutorial which reinforces the concepts rather than trying to do both at the same time.
On the other hand, if someone had experience of polymorphism in another language and just needed to learn how to do it in C++, then the tutorial would be rather different.
Basically, you need to know your audience when writing a tutorial. What level of background knowledge will they already have? If it’s not enough to understand the tutorial, then perhaps the background knowledge needs to be taught before that particular tutorial. For example, you wouldn’t show your reversing tutorials to someone who’s just managed “Hello World” and expect them to get on with it.
April 16, 2007
Your point about overloading the reader with information is a very good one. Katherine would definitely know more about this than me
And so we come to the moot point
How much background information should be in the tutorial? I think that it’ll very a lot depending on the subject matter.
I guess the reason I thought about it was because I thought that background information was lacking in a few of the things I’ve read recently. I don’t expect a full history of the subject, but I do expect snippets that are going to aid in understanding particulars about certain examples.
So, back to the example I gave about unpacking. If I was going to write a tutorial about unpacking exes that are packed with UPX, I wouldn’t just say “run this and click here”. I would explain why. Why was the button clicked? Why not another button? Why is the memory address important when unpacking this particular type of exe? Why should you take note of certain things along the way? How would referencing an address at a different type miss the point of the article? What are the repercussions if you don’t put a breakpoint at the right spot? Why is it that the address varies across compression schemes? The list goes on
So the two-second “run that, press that” tutorial really doesn’t deliver that much information. To me, it should explain it in such a way that you would understand the means to unpack UPX exes even if you didn’t have the tools handy to allow you to do it. That’s basically my gripe! In this example, the tutorial shouldn’t be called “How to unpack UPX”, it should be called “How to unpack UPX in 2 seconds using X, Y and Z”. At least then my hopes wouldn’t be high 
Good feedback though dude!
April 18, 2007
hi OJ, and hello everybody, man i don’t mind if you put my name, let everybody see an example of bad tutorial, this is the way i see it, at least i’m learning something here. good to met OJ and thank for the tutorials.
next tutorial will be dedicated for you.
azmo/aore
April 19, 2007
Hi Azmo,
Thanks to posting mate
I’d like to point out that I don’t think your tutorials are bad. I certainly don’t think they’re useless, and I do think that there is meaningful information in them.
The point of the discussion was to highlight the possibility of providing more information to aid in understanding - which is the point of a tutorial. As I said, my definition of a tutorial is a little different to most people’s, but that doesn’t mean I think that everyone else’s work is terrible.
Please don’t think that I feel your tutorials are poor. What I do think is that with just a bit more information, they would become a lot more helpful, and people would get a lot more out of watching/reading them.
If you like, maybe we can team up and write something that covers this level of information? Then it could be released in both Arabic and English - you do the Arabic version, I’ll do the English version, and we’ll see what the community thinks of it?
What do you think?
Cheers, and thanks for stopping by.
OJ
April 19, 2007
I have a take on tutorials as well… but it might be from a different angle to others here. I teach visual communicators at UTS fundamental principles behind HTML/CSS and introductory Actionscript. My classes are a combination of tutorial and lecture, and I agree OJ, it’s fundamental (there’s that word again) in my opinion, that the students understand why they are doing what they do.
I remember my geography teacher (who had a love for the overhead projector) saying something like “Don’t just copy what I put up. If you don’t understand it - it’s useless.” Now perpahs it’s just me, but I agree with him… because if I don’t tell them, invariably (as the students are an inquisitive lot) they at some stage are gonna ask. And if they don’t (from experience), their learning will suffer.
But to the point : the lecture is where this deeper knowledge gets developed. But it’s the tutorial where we put it into practice - hand-holding, step by steps, a little “click this, press that” and a little “now, give it a go yourselves” etc.
I’m not so great with the written side of things - which I guess is where my point of view finishes. What I tend to do is suppliment my classes with text and a few examples : http://www.shiftperception.com/uts/webmedia1/ (for example). It seems to work, although I know there is heaps of room for improvement.
So, what constitutes a totorial… I think a tutorial (at least in my mind) certainly has a level of hand holding… sing along with me… walk this way etc (as in the definition), but yeah - seems to have absorbed the notion of a lecture into it when presented electronically. Perhaps a way forward is to include a 5 min lecture at the start of the tutorial (as a video ??), or optional links to some fundamental understandings - like a list of prerequisits to understanding?
/dan
April 19, 2007
Great post Dan. Again highlighting some interesting points.
A key point for me is that a tutorial should consolidate your understanding, and in conslidating it should briefly recap key points on the topic. If it doesn’t do that then it doesn’t necessarily aid in the learning. If no knowledge is consolidated, the tutorial isn’t as effective as it should be
IMHO
April 19, 2007
Yep, agreed.
April 19, 2007
Hi OJ, sorry it came out wrong (English is not my native language, so please excuse me); I know that you don’t think that the tutorials are bad, but it was poor choice of words.
Anyway, I must admit that sometimes I have trouble in explaining the information, I know it but I can’t deliver it to someone else. This is why I thought a video will explain more. And to let the viewer see what I do and how I do it will save me the trouble of explaining simple thing in paragraph after paragraph without hitting the point. And I’m not saying this because I’m lazy to write, no, but I get lost in my own writing sometimes and I can’t focus on what was the subject in the first place.
Apparently I was wrong to some extent; I mean a lot of the Arabic viewers thought that this was good and they appreciated the idea and told me that they are learning something; maybe they are learning the mechanical way of doing things but leaving the thinking way aside. This is another reason for keeping the tutorials in the sense of “do this and press that”. But on the other side of the world like my mate OJ here, showed me another perspective and I totally agree that a tutorial should provide more information to aid in understanding.
I’ll take the offer of teaming up and write something that covers any level of information. I’ll be more than happy to work with you and to learn from you.
Thx OJ,
azmo
April 19, 2007
Hi again Azmo,
Excellent! I’ll have a think about some things that we can work on and I’ll get in touch with you!
Cheers
OJ