How many times have you started reading a tutorial, and it begins introducing new concepts without explaining them? Or it uses words and terms that you don't understand?
I think it's obvious what the main problem is. The authors of the tutorials assume that the reader knows a lot more about the topic than they actually do.
Some time ago, I wanted to learn about DOCTYPEs (in relation to web sites). If you view the HTML source of a webpage, look right at the top and you'll see something like:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
What is it? Googling around, I found out it had something to do with "XHTML" and "web standards". But what actually is it? What is it doing there? Why is it there? What problem is it solving? Don't bother trying to get your answer from an online tutorial about DOCTYPEs.
Let's take the opening paragraph from this online tutorial about what DOCTYPEs are (from ZVON):
"An XML document is valid if it has an associated document type definition and if the document complies with the constraints expressed in it. The document type definition must appear before the first element in the document. The name following the word DOCTYPE in the document type definition must match the name of root element."
WHAT?!
For someone who knows nothing about DOCTYPEs, how would they read that above paragraph? Probably something like:
What is an XML document? What do you mean "is valid"? I don't know what "document type definition" is, let alone what an "associated" one is. As for the last sentence... no clue.
I should of course be gentle. That sentence obviously made perfect sense to the author who wrote it, because he/she would understand all of the terms used. Perhaps the tutorial is aimed at people who have an existing thorough knowledge of related areas. But to a novice trying to learn about DOCTYPEs from that "explanation", it would be of no help at all.
In my next post, I'll list a simple set of rules that I think every online tutorial should follow (but almost none do). I hope this website/blog can be a reliable place for novices to get quality tutorials, examples of good tutorials, and links to other sites carrying good tutorials!
Let's take the opening paragraph from this online tutorial about what DOCTYPEs are (from ZVON):
"An XML document is valid if it has an associated document type definition and if the document complies with the constraints expressed in it. The document type definition must appear before the first element in the document. The name following the word DOCTYPE in the document type definition must match the name of root element."
WHAT?!
For someone who knows nothing about DOCTYPEs, how would they read that above paragraph? Probably something like:
What is an XML document? What do you mean "is valid"? I don't know what "document type definition" is, let alone what an "associated" one is. As for the last sentence... no clue.
I should of course be gentle. That sentence obviously made perfect sense to the author who wrote it, because he/she would understand all of the terms used. Perhaps the tutorial is aimed at people who have an existing thorough knowledge of related areas. But to a novice trying to learn about DOCTYPEs from that "explanation", it would be of no help at all.
In my next post, I'll list a simple set of rules that I think every online tutorial should follow (but almost none do). I hope this website/blog can be a reliable place for novices to get quality tutorials, examples of good tutorials, and links to other sites carrying good tutorials!
No comments:
Post a Comment