Monday, December 17, 2007

Five simple rules that online tutorials should follow

Although this blog (for now) is going to focus only on web development tutorials, I believe that the qualities that make a tutorial easy to understand are universal. So here we go:

5 Simple Rules that every person who writes online tutorials should follow:

*Always define your audience, and write only with them in mind
Decide who you are writing the tutorial for, and any required skills/knowledge they should already have. When deciding on this, remember that you want your tutorial to appeal to as many people as possible.

*Do not introduce any new concept or idea unless you are certain that the target audience knows precisely what you are talking about
This is the number one failing of almost every online tutorial. You're reading a tutorial on an introduction to HTML, and you're seeing terms like "web standards" and "cross browser support" without any useful idea what these terms actually mean.

*Don't use words that some people may not know the exact meaning of
This is referring to words in the language that the tutorial is being written in (in this case, english). For example, don't use words like "ambiguous" or "ubiquitous". Instead use "confusing" and "everywhere".

*Don't use any unnecessary words or sentences
Keep sentences as short as possible. Eliminate words that don't need to be there.

*Make it clear and obvious what problem is being solved by the new skill that is being taught
Another major common failing of online tutorials is that they begin explaining a concept without giving the reader a clear understanding of what problem it is solving. Every new technology and innovation in the history of mankind was invented to solve a problem. Before teaching the new concept, make sure the reader has a clear and practical idea (use examples) of what the problem is that is being solved. This will almost certainly involve explaining some history or evolution of the concept.

Coming up in my next post - my attempt at writing the beginning of a tutorial that will follow these rules. The tutorial will be on HTML DOCTYPEs, given that I touched on them in my previous post. The intended audience will be those with a basic understanding of HTML and CSS.

Can you help me improve these list of rules that every online tutorial should follow? Please make suggestions in the Comments section of this post.

No comments: